Index: Doc/lib/libmailbox.tex
===================================================================
--- Doc/lib/libmailbox.tex	(revision 53260)
+++ Doc/lib/libmailbox.tex	(working copy)
@@ -51,6 +51,16 @@
 \exception{KeyError} exception if the corresponding message is subsequently
 removed.
 
+Be very cautious when modifying mailboxes that might also be modified
+by some other process such as a mail transport agent or a different
+Python process.  The safest mailbox format to use for such tasks is
+Maildir; avoid using single-file formats such as mbox.  If you're
+modifying a mailbox, no matter what the format, you must lock it by
+calling the \method{lock()} and \method{unlock()} methods before
+making any changes.  If you don't do this, you run the risk of losing
+data because one process makes changes to the mailbox that the other
+process is unaware of.
+
 \class{Mailbox} itself is intended to define an interface and to be inherited
 from by format-specific subclasses but is not intended to be instantiated.
 Instead, you should instantiate a subclass.
@@ -202,15 +212,16 @@
 
 \begin{methoddesc}{flush}{}
 Write any pending changes to the filesystem. For some \class{Mailbox}
-subclasses, changes are always written immediately and this method does
-nothing.
+subclasses, changes are always written immediately and \method{flush()} does
+nothing, but you should still make a habit of calling this method.
 \end{methoddesc}
 
 \begin{methoddesc}{lock}{}
 Acquire an exclusive advisory lock on the mailbox so that other processes know
 not to modify it. An \exception{ExternalClashError} is raised if the lock is
 not available. The particular locking mechanisms used depend upon the mailbox
-format.
+format.  You should \emph{always} lock the mailbox before making any 
+modifications to its contents.
 \end{methoddesc}
 
 \begin{methoddesc}{unlock}{}
@@ -1373,8 +1384,11 @@
 \begin{verbatim}
 import mailbox
 destination = mailbox.MH('~/Mail')
+destination.lock()
 for message in mailbox.Babyl('~/RMAIL'):
     destination.add(MHMessage(message))
+destination.flush()
+destination.unlock()
 \end{verbatim}
 
 An example of sorting mail from numerous mailing lists, being careful to avoid
@@ -1397,12 +1411,19 @@
         list_id = message['list-id']
         if list_id and name in list_id:
             box = boxes[name]
+	    # Write copy to disk before removing original.
             box.lock()
             box.add(message)
-            box.flush()         # Write copy to disk before removing original.
+            box.flush()         
             box.unlock()
+
+            # Remove original message
+            inbox.lock()
             inbox.discard(key)
+	    inbox.flush()
+            inbox.unlock()
             break               # Found destination, so stop looking.
+
 for box in boxes.itervalues():
     box.close()
 \end{verbatim}