/offlineimap/head: changeset 344

[offlineimap] / offlineimap / head / offlineimap.sgml

diff --git a/offlineimap/head/offlineimap.sgml b/offlineimap/head/offlineimap.sgml
index 236da91a73067e8af87816fb1dd657f430052162..9433d4fab5eb33b8b469eccf5ea24647c0a43a56 100644 (file)
--- a/offlineimap/head/offlineimap.sgml
+++ b/offlineimap/head/offlineimap.sgml
@@ -11,7 +11,7 @@
     <refentryinfo>
       <address><email>jgoerzen@complete.org</email></address>
       <author><firstname>John</firstname><surname>Goerzen</surname></author>
-      <date> $Date: 2003-01-08 09:08:01 -0600 (Wed, 08 Jan 2003) $ </date>
+      <date> $Date: 2003-01-08 09:13:21 -0600 (Wed, 08 Jan 2003) $ </date>
     </refentryinfo>
 
     <refmeta>
@@ -676,7 +676,64 @@ def test_mycmp():
       </refsect2>
     </refsect1>
       
+    <refsect1>
+      <title>Errors</title>
+      <para>
+       If you get one of some frequently-encountered or confusing errors,
+       please check this section.
+      </para>
+      
+      <refsect2>
+       <title>UID validity problem for folder</title>
+       <para>IMAP servers use a unique ID (UID) to refer to a specific message.
+         This number is guaranteed to be unique to a particular message
+         <emphasis>forever</emphasis>.
+         No other message in the same folder will ever get the same
+         UID.  UIDs are an integral part of &OfflineIMAP;'s synchronization
+         scheme; they are used to match up messages on your computer to
+         messages on the server.
+       </para>
+
+       <para>
+         Sometimes, the UIDs on the server might get reset.  Usually this will
+         happen if you delete and then recreate a folder.  When you create a
+         folder, the server will often start the UID back from 1.  But
+         &OfflineIMAP; might still have the UIDs from the previous folder by the
+         same name stored.  &OfflineIMAP; will detect this condition and skip the
+         folder.  This is GOOD, because it prevents data loss.
+       </para>
+
+       <para>
+         You can fix it by removing your local folder and cache data.  For
+         instance, if your folders are under <filename>~/Folders</filename>
+         and the folder with the problem is INBOX, you'd type this:
+       </para>
+
+       <programlisting>rm -r ~/Folders/INBOX
+rm -r ~/.offlineimap/AccountName/INBOX</programlisting>
+
+       <para>
+         (Of course, replace AccountName with the account name as specified
+         in <filename>~/.offlineimaprc</filename>).
+       </para>
 
+       <para>Next time you run &OfflineIMAP;, it will re-download
+         the folder with the
+         new UIDs.  Note that the procedure specified above will lose any local
+         changes made to the folder.
+       </para>
+
+       <para>
+         Some IMAP servers are broken and do not support UIDs properly.  If you
+         continue to get this error for all your folders even after performing
+         the above procedure, it is likely that your IMAP server falls into
+         this category.  &OfflineIMAP; is incompatible with such servers.
+         Using &OfflineIMAP; with them will not destroy any mail, but at the same time,
+         it will not actually synchronize it either.  (&OfflineIMAP; will detect
+         this condition and abort prior to synchronization.)
+       </para>
+      </refsect2>
+    </refsect1>
 
     <refsect1>
       <title>See Also</title>