Add documentation

1 files changed, 44 insertions, 0 deletions

diff --git a/doc/mum.ms b/doc/mum.ms
new file mode 100644
index 0000000..358bcab
--- /dev/null
+++ b/doc/mum.ms
@@ -0,0 +1,44 @@
+.TL
+mum \(en modern UNIX mail interface
+.AU
+John Ankarström
+.SH
+Introduction
+.LP
+Mum is a text-based e-mail client for UNIX and UNIX-like operating
+systems that supports both plain-text and HTML e-mail.
+It introduces a new method for local storage of e-mail, called
+indexed mbox.
+Furthermore, it uses
+.I views
+\(en simple scripts that filter messages \(en instead of folders.
+.PP
+In this document, the fundamental concepts of mum are explained.
+.SH
+The indexed mbox format
+.LP
+There are two popular methods for local storage of e-mail on UNIX
+systems: mbox and Maildir.
+Maildir is a powerful but complicated solution, while mbox is a
+simple but inefficient solution.  The "indexed mbox" format introduced
+by mum builds on the mboxcl2 format, but enhances it with an
+additional file called an
+.I index ,
+which carries the same name as the mbox plus the extension
+.I .i .
+The index contains all headers from the mbox file, including the
+.I From_
+line, without the actual contents of the corresponding messages.
+Each block of headers contains an additional header called
+.I Offset ,
+which contains the position of the corresponding message in the
+mbox file, described as a byte offset.
+Additionally, a
+.I Content-Length
+header is included in both mbox and mbox.i.
+(Note further that the mbox and mbox.i files are append-only.)
+.PP
+Mum and its associated view scripts use the index for most operations.
+Whenever it is time to read the actual contents of a message, the
+message is retrieved from the mbox using the offset specified in
+the index.