]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/lei-mail-formats.pod
doc: acknowledge the MMDF mailbox format
[public-inbox.git] / Documentation / lei-mail-formats.pod
1 =head1 NAME
2
3 lei-mail-formats - description of mail formats supported by lei
4
5 =head1 DESCRIPTION
6
7 L<lei-q(1)> supports writing to several existing mail formats
8 for interoperability with existing mail user agents (MUA);
9 below is an overview of them to help users choose.
10
11 =head1 Maildir
12
13 The default output format when given a filesystem path, it supports
14 parallel read-write access.  Performance is acceptable for smaller
15 directories, but degrades as mailboxes get larger.  Speed and
16 scalability are limited by kernel and filesystem performance
17 due to the use of small files and large number of syscalls.
18
19 See also: L<https://cr.yp.to/proto/maildir.html> and
20 L<https://wiki2.dovecot.org/MailboxFormat/Maildir>
21
22 =head1 Mbox family
23
24 The mbox family consists of several incompatible formats.
25 Locking for parallel access is supported, but may not be
26 compatible across tools.  With compression (e.g. L<gzip(1)>),
27 they require the least amount of space while offering good
28 read-only performance.
29
30 Keyword updates (C<Status:> and/or C<X-Status:> headers)
31 generally require rewriting the entire mbox.
32
33 See also:
34 L<https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>,
35 L<mbox(5)>
36
37 =head2 mboxo
38
39 The traditional BSD format.  It quotes C<From > to C<E<gt>From >,
40 but lines already beginning with C<E<gt>From > do not get quoted,
41 thus automatic reversibility is not guaranteed.  MUAs which favor
42 L</mboxcl> or L</mboxcl2> may convert these automatically to their
43 preferred format.
44
45 Truncation is undetectable unless compressed with gzip or similar.
46
47 =head2 mboxrd
48
49 An evolution of L</mboxo>, but quotes C<From > lines prefixed
50 with any number of C<E<gt>> characters and is thus fully
51 reversible.
52
53 This format is emitted by L<PublicInbox::WWW(3pm)> with gzip.
54 It is supported by L<git-am(1)> since git 2.10.
55
56 As with uncompressed L</mboxo>, uncompressed mboxrd are vulnerable
57 to undetectable truncation.
58
59 It gracefully degrades to being treated as L</mboxo> by MUAs
60 unaware of the format as excessive C<E<gt>From > quoting is
61 recognizable to humans.
62
63 =head2 mboxcl
64
65 L</mboxo> with a C<Content-Length:> header, C<From > lines
66 remain quoted to retain readability with L</mboxo> and L</mboxrd> MUAs.
67 However, it is easy to corrupt these files when using tools
68 which are not aware of C<Content-Length:> and write out updates
69 as L</mboxo>.
70
71 L<mutt(1)> will convert L</mboxo> and L</mboxrd> to mboxcl upon opening.
72
73 See also: L<https://www.jwz.org/doc/content-length.html>
74
75 =head2 mboxcl2
76
77 Like L</mboxcl>, but without C<From > any quoting.  It is wholly
78 incompatible with MUAs which only handle L</mboxo> and/or L</mboxrd>.
79 This is format is generated by L<mutt(1)> when writing to a new
80 mbox.
81
82 =head1 MH
83
84 Not yet supported, locking semantics (or lack thereof) appear to
85 make it unsuitable for parallel access.  It is widely-supported
86 by a variety of MUAs and mailing list managers, however.
87
88 =head1 MMDF
89
90 Not yet supported, and it's unclear if current usage/support makes
91 it worth supporting.
92
93 =head1 IMAP
94
95 Depending on the IMAP server software and configuration, IMAP
96 servers may use any (or combination) of the aforementioned
97 formats or a non-standard database backend.
98
99 =head1 COPYRIGHT
100
101 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
102
103 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
104
105 =head1 SEE ALSO
106
107 L<lei(1)>, L<lei-q(1)>, L<lei-convert(1)>, L<lei-overview(7)>