- ## broken? means no message can be loaded, e.g. IMAP server is
- ## down, mbox file is corrupt and needs to be rescanned.
-
- ## When writing a new source, you should implement:
+ ## In particular, Sup doesn't need to move messages, mark them as
+ ## read, delete them, or anything else. (Well, it's nice to be able
+ ## to delete them, but that is optional.)
+ ##
+ ## On the other hand, Sup assumes that you can assign each message a
+ ## unique integer id, such that newer messages have higher ids than
+ ## earlier ones, and that those ids stay constant across sessions
+ ## (in the absence of some other client going in and fucking
+ ## everything up). For example, for mboxes I use the file offset of
+ ## the start of the message. If a source does NOT have that
+ ## capability, e.g. IMAP, then you have to do a little more work to
+ ## simulate it.
+ ##
+ ## To write a new source, subclass this class, and implement:
+ ##
+ ## - start_offset
+ ## - end_offset (exclusive!)
+ ## - load_header offset
+ ## - load_message offset
+ ## - raw_header offset
+ ## - raw_message offset
+ ## - check
+ ## - next (or each, if you prefer): should return a message and an
+ ## array of labels.
+ ##
+ ## ... where "offset" really means unique id. (You can tell I
+ ## started with mbox.)