From 2ead447bb831072fae5d2ddf7360abc3f30f141f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Sun, 22 Nov 2020 10:48:47 +0100
Subject: mboxu.5: Update and clarify

---
 mboxu.5 | 60 ++++++++++++++++++++++++++++++++----------------------------
 1 file changed, 32 insertions(+), 28 deletions(-)

diff --git a/mboxu.5 b/mboxu.5
index 1380282..a785777 100644
--- a/mboxu.5
+++ b/mboxu.5
@@ -4,51 +4,55 @@
 .
 .Sh NAME
 .Nm mboxu
-.Nd mbox in UTF-8
+.Nd readable mbox format
 .
 .
 .Sh DESCIPTION
 .Pp
 .Nm
-is a simple and readable mbox-like format, in which messages are encoded directly in UTF-8.
+is a simple and readable mbox-like format, in which messages are encoded in UTF-8.
 
-Messages are differentiated from one another via a line beginning with
-.Ql From\  ,
-.Em followed by at least one header line .
-
-Otherwise,
+In addition,
+.Nm
+forbids the inclusion of multipart messages inside the mbox database.
+Only the
+.Em canonical
+part, formatted in plain-text UTF-8, is included inside the mbox file.
+Other parts, such as images, should be stored in separate local files and referenced via an
+.Ql Attachment
+header:
+.
+.Bd -literal -offset indent
+Attachment: att/review.pdf
+.Ed
+.
+.Pp
+Paths in the
+.Ql Attachment
+header are relative to the location of the mbox database, unless they begin with a forward slash.
+.Pp
 .Nm
-is identical to traditional mbox.
+is readable by most modern mail readers.
+Attachments are not directly visible, but can be accessed manually through the
+.Ql Attachment
+headers.
 .
 .Sh RATIONALE
 .Pp
+RFC 4155 requires messages stored in mbox databases to follow the standard syntax and format of e-mail messages defined in RFC 2822 (but without the carriage return).
+It also requires messages to be seven-bit text, such as ASCII or presumably UTF-7.
+.Pp
+This makes it difficult to use mbox for anything other than storing received mail on an internet mail server.
+.Pp
 .Nm
-has two goals:
+simplifies the mbox format in order to expand its usage to the storage of other data than real internet mail.
+It has two goals:
 .Bl -enum
 .It
 to be easily writable and readable by humans, and
 .It
 to be easily generated and parsed by machines.
 .El
-.Pp
-Normally, non-ASCII e-mail messages must be encoded in base64 or quoted-printable, rendering them more or less unreadable in raw form.
-Mailboxes using
-.Nm ,
-on the other hand, do not require any decoding to be read by a human.
-
-Likewise,
-.Nm
-is much easier to generate and manually write than standard mbox.
-.
-.Sh FUTURE
-.Pp
-In the future, a readable alternative to multipart messages may be added, where non-canonical parts are stored in separate files and referenced via some
-.Ql Attachment:
-header.
-.Pp
-If that is added, a translator between
-.Nm
-and standard mbox might be desirable.
 .
 .Sh AUTHORS
 .Pp
-- 
cgit v1.2.3