manual: add known issues entry about XOAUTH2 "invalid_grant"

- Split the manual asciidoc source file.
- Improve the Makefile to build the manuals.

Github-ref: https://github.com/OfflineIMAP/offlineimap/issues/374
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>

docs/offlineimap.txt

@@ -335,103 +335,7 @@ process core.
 Known Issues
 ------------
 
-* SSL3 write pending.
-+
-Users enabling SSL may hit a bug about "SSL3 write pending". If so, the
-account(s) will stay unsynchronised from the time the bug appeared. Running
-OfflineIMAP again can help. We are still working on this bug.  Patches or
-detailed bug reports would be appreciated. Please check you're running the
-last stable version and send us a report to the mailing list including the
-full log.
-
-* IDLE support is incomplete and experimental. Bugs may be encountered.
-
-  - No hook exists for "run after an IDLE response".
-+
-Email will show up, but may not be processed until the next refresh cycle.
-
-  - nametrans may not be supported correctly.
-
-  - IMAP IDLE <-> IMAP IDLE doesn't work yet.
-
-  - IDLE might stop syncing on a system suspend/resume.
-
-  - IDLE may only work "once" per refresh.
-+
-If you encounter this bug, please send a report to the list!
-
-* Maildir support in Windows drive.
-+
-Maildir uses colon caracter (:) in message file names. Colon is however
-forbidden character in windows drives. There are several workarounds for that
-situation:
-
-    . Enable file name character translation in windows registry (not tested).
-      - <http://support.microsoft.com/kb/289627>
-
-    . Use cygwin managed mount (not tested).
-      - not available anymore since cygwin 1.7
-
-    . Use "maildir-windows-compatible = yes" account OfflineIMAP configuration.
-      - That makes OfflineIMAP to use exclamation mark (!) instead of colon for
-        storing messages. Such files can be written to windows partitions. But
-        you will probably loose compatibility with other programs trying to
-        read the same Maildir.
-+
-      - Exclamation mark was chosen because of the note in
-        http://docs.python.org/library/mailbox.html
-+
-      - If you have some messages already stored without this option, you will
-        have to re-sync them again
-
-* OfflineIMAP confused after system suspend.
-+
-When resuming a suspended session, OfflineIMAP does not cleanly handles the
-broken socket(s) if socktimeout option is not set.
-You should enable this option with a value like 10.
-
-* OfflineIMAP confused when mails change while in a sync.
-+
-When OfflineIMAP is syncing, some events happening since the invocation on
-remote or local side are badly handled. OfflineIMAP won't track for changes
-during the sync.
-
-
-* Sharing a maildir with multiple IMAP servers.
-+
-Generally a word of caution mixing IMAP repositories on the same Maildir root.
-You have to be careful that you *never* use the same maildir folder for 2 IMAP
-servers. In the best case, the folder MD5 will be different, and you will get
-a loop where it will upload your mails to both servers in turn (infinitely!)
-as it thinks you have placed new mails in the local Maildir. In the worst
-case, the MD5 is the same (likely) and mail UIDs overlap (likely too!) and it
-will fail to sync some mails as it thinks they are already existent.
-+
-I would create a new local Maildir Repository for the Personal Gmail and
-use a different root to be on the safe side here. You could e.g. use
-
-    `~/mail/Pro' as Maildir root for the ProGmail and
-    `~/mail/Personal' as root for the personal one.
-+
-If you then point your local mutt, or whatever MUA you use to `~/mail/'
-as root, it should still recognize all folders.
-
-
-* Edge cases with maxage causing too many messages to be synced.
-+
-All messages from at most maxage days ago (+/- a few hours, depending on
-timezones) are synced, but there are cases in which older messages can also be
-synced. This happens when a message's UID is significantly higher than those of
-other messages with similar dates, e.g. when messages are added to the local
-folder behind offlineimap's back, causing them to get assigned a new UID, or
-when offlineimap first syncs a pre-existing Maildir. In the latter case, it
-could appear as if a noticeable and random subset of old messages are synced.
-
-* Passwords in netrc.
-+
-Offlineimap doesn't know how to retrieve passwords when more than one account is
-stored in the netrc file. See
-<https://github.com/OfflineIMAP/offlineimap/issues/295>.
+include::./offlineimap.known_issues.txt[]
 
 
 Main authors