diff options
Diffstat (limited to 'Documentation/lei-mail-formats.pod')
-rw-r--r-- | Documentation/lei-mail-formats.pod | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/Documentation/lei-mail-formats.pod b/Documentation/lei-mail-formats.pod new file mode 100644 index 00000000..618bada2 --- /dev/null +++ b/Documentation/lei-mail-formats.pod @@ -0,0 +1,138 @@ +=head1 NAME + +lei-mail-formats - description of mail formats supported by lei + +=head1 DESCRIPTION + +L<lei-q(1)> supports writing to several existing mail formats +for interoperability with existing mail user agents (MUA); +below is an overview of them to help users choose. + +=head1 Maildir + +The default output format when given a filesystem path, it supports +parallel read-write access. Performance is acceptable for smaller +directories, but degrades as mailboxes get larger. Speed and +scalability are limited by kernel and filesystem performance +due to the use of small files and large number of syscalls. + +See also: L<https://cr.yp.to/proto/maildir.html> and +L<https://wiki2.dovecot.org/MailboxFormat/Maildir> + +=head1 Mbox family + +The mbox family consists of several incompatible formats. +Locking for parallel access is supported, but may not be +compatible across tools. With compression (e.g. L<gzip(1)>), +they require the least amount of space while offering good +read-only performance. + +Keyword updates (C<Status:> and/or C<X-Status:> headers) +generally require rewriting the entire mbox. + +See also: +L<https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>, +L<mbox(5)> + +=head2 mboxo + +The traditional BSD format. It quotes C<From > to C<E<gt>From >, +but lines already beginning with C<E<gt>From > do not get quoted, +thus automatic reversibility is not guaranteed. MUAs which favor +L</mboxcl> or L</mboxcl2> may convert these automatically to their +preferred format. + +Truncation is undetectable unless compressed with gzip or similar. + +=head2 mboxrd + +An evolution of L</mboxo>, but quotes C<From > lines prefixed +with any number of C<E<gt>> characters and is thus fully +reversible. + +This format is emitted by L<PublicInbox::WWW(3pm)> with gzip. +Since git 2.10, C<git am --patch-format=mboxrd> reads this +format. C<git log> and C<git format-patch --stdout> can also +generate this format with the C<--pretty=mboxrd> switch. + +As with uncompressed L</mboxo>, uncompressed mboxrd are vulnerable +to undetectable truncation. + +It gracefully degrades to being treated as L</mboxo> by MUAs +unaware of the format as excessive C<E<gt>From > quoting is +recognizable to humans. + +=head2 mboxcl + +L</mboxo> with a C<Content-Length:> header, C<From > lines +remain quoted to retain readability with L</mboxo> and L</mboxrd> MUAs. +However, it is easy to corrupt these files when using tools +which are not aware of C<Content-Length:> and write out updates +as L</mboxo>. + +L<mutt(1)> will convert L</mboxo> and L</mboxrd> to mboxcl upon opening. + +See also: L<https://www.jwz.org/doc/content-length.html> + +=head2 mboxcl2 + +Like L</mboxcl>, but without C<From > any quoting. It is wholly +incompatible with MUAs which only handle L</mboxo> and/or L</mboxrd>. +This is format is generated by L<mutt(1)> when writing to a new +mbox. + +=head1 MH + +Preliminary support for reads as of 2.0.0. Locking semantics differ +incompatibly amongst existing writers: Python and nmh appear +compatible with each other, while mutt appears racy and unsuitable +for parallel access due to rename(2) potentially clobbering the +C<.mh_sequences> file. More info about other clients is greatly +appreciated. + +Sequence numbers may be packed and reused by some writers, so lei +users may need to run L<lei-refresh-mail-sync(1)> if inotify|kevent +missed packing while L<lei-daemon(8)> wasn't running. + +lei is safe for reading mlmmj archives as MH since mlmmj neither +packs nor uses a .mh_sequences file to store state. + +=head1 MMDF + +Not yet supported, and it's unclear if current usage/support makes +it worth supporting. + +=head1 IMAP + +Depending on the IMAP server software and configuration, IMAP +servers may use any (or combination) of the aforementioned +formats or a non-standard database backend. Currently, lei +uses L<Mail::IMAPClient> which has acceptable performance +over low-latency links. Performance over high-latency links +is currently poor. + +=head1 eml + +A single raw message file. C<eml> is not an output format for lei, +but accepted by as an C<--input-format> (C<-F>) for read-only +commands such as L<lei-tag(1)> and L<lei-import(1)>. + +Since C<eml> is the suffix for the C<message/rfc822> MIME type +(according to the C<mime.types> file), lei will infer the type +based on the C<.eml> suffix if C<--input-format> is unspecified + +C<.patch>-suffixed files generated by L<git-format-patch(1)> +(without C<--stdout>) are C<eml> files with the addition of an +mbox C<From > header. L<lei(1)> removes C<From > lines to treat +them as C<eml> when reading these for compatibility with +C<git-am(1)> and similar tools. + +=head1 COPYRIGHT + +Copyright 2021 all contributors L<mailto:meta@public-inbox.org> + +License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt> + +=head1 SEE ALSO + +L<lei(1)>, L<lei-q(1)>, L<lei-convert(1)>, L<lei-overview(7)> |