Source from upstream; imap-2007f.tar.gz

MD5 2126fd125ea26b73b20f01fcd5940369

docs/commndmt.txt

@@ -0,0 +1,101 @@
+/* ========================================================================
+ * Copyright 1988-2006 University of Washington
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 
+ * ========================================================================
+ */
+
+[I wrote this tongue-in-cheek, but there's a lot here that people who
+ build IMAP clients should take careful note.  Most existing clients
+ violate at least one, generally several, of these commandments.
+ These are based on known user-visible problems that occur with various
+ commonly used clients.  Put another way, behind each commandment is a
+ plethora of user (and server administrator) complaints caused by a
+ violator.]
+
+	   Ten Commandments of How to Write an IMAP client
+			     Mark Crispin
+
+1. Thou shalt not assume that it is alright to open multiple IMAP
+sessions selected on the same mailbox simultaneously, lest thou face
+the righteous wrath of mail stores that doth not permit such access.
+Instead, thou shalt labor mightily, even unto having to use thy brain
+to thinketh the matter through, such that thy client use existing
+sessions that are already open.
+
+2. Thou shalt not abuse the STATUS command by using it to check for
+new mail on a mailbox that you already have selected in an IMAP
+session; for that session hath already told thou about new mail
+without thy having to ask.
+
+3. Thou shalt remember the 30 minute inactivity timeout, and remember
+to speak to the IMAP server before that timeout expires.  If thou
+useth the IDLE command, thou shalt send DONE from the IDLE before 29
+minutes hath passed, and issue a new IDLE.  If thou maketh no use of
+IDLE, then thou shalt send NOOP every few minutes, and the server
+shalt tell you about new mail, and there will be much rejoicing in the
+land.
+
+4. Thou shalt not assume that all names are both the name of a mailbox
+and the name of a upper level of hierarchy that contains mailboxes;
+lest thou face the righteous wrath of mail stores in which a mailbox
+is a file and a level of hierarchy is a directory.  Thou shalt pay
+diligent attention to the \NoSelect and \NoInferiors flags, so that
+your users may praise you with great praise.
+
+5. Thou shalt learn and understand the unique features of IMAP, such
+as the unsolicited data model, the strict ascending rule of UIDs, how
+UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE
+structures; so that thou may use the IMAP protocol effectively.  For a
+POP client hacked to babble IMAP protocol is still no more than a POP
+client.
+
+6. Thou shalt remember untagged data sent by the server, and when thou
+needest data thou shalt consult your memory before asking the server.
+For those who must analyze thy protocol transactions are weak of
+stomach, and are likely to lose their recent meal should they see thou
+repeatedly re-fetch static data.
+
+7. Thou shalt labor with great effort to work within the IMAP
+deleted/expunge model, even if thy own model is that of a trashcan;
+for interoperability is paramount and a trashcan model can be done
+entirely in the user interface.
+
+8. Thou shalt not fear to open multiple IMAP sessions to the server;
+but thou shalt use this technique with wisdom.  For verily it is true;
+if thou doth desire to monitor continuously five mailboxes for new
+mail, it is better to have five IMAP sessions continuously open on the
+mailboxes.  It is generally not good to do a succession of five SELECT
+or STATUS commands on a periodic basis; and it is truly wretched to
+open and close five sessions to do a STATUS or SELECT on a periodic
+basis.  The cost of opening and closing a session is great, especially
+if that session is SSL/TLS protected; and the cost of a STATUS or
+SELECT can also be great.  By comparison, the cost of an open session
+doing an IDLE or getting a NOOP every few minutes is small.  Great
+praise shall be given to thy wisdom in doing what is less costly
+instead of "common sense."
+
+9. Thou shalt not abuse subscriptions, for verily the LIST command is
+the proper way to discover mailboxes on the server.  Thou shalt not
+subscribe names to the user's subscription list without explicit
+instructions from the user; nor shalt thou assume that only subscribed
+names are valid.  Rather, thou shalt treat subscribed names as akin to
+a bookmarks, or perhaps akin to how Windows shows the "My Documents"
+folder -- a set of names that are separate from the hierarchy, for
+they are such.
+
+10. Thou shalt use the LIST "*" wildcard only with great care.  If
+thou doth not fully comprehend the danger of "*", thou shalt use only
+"%" and forget about the existance of "*".
+
+Honor these commandments, and keep them holy in thy heart, so that thy
+users shalt maximize their pleasure, and the server administrators
+shalt sing thy praises and recommend thy work as a model for others to
+emulate.
+