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 Since git 2.10, C<git am --patch-format=mboxrd> reads this
  55 format.  C<git log> and C<git format-patch --stdout> can also
  56 generate this format with the C<--pretty=mboxrd> switch.
  57
  58 As with uncompressed L</mboxo>, uncompressed mboxrd are vulnerable
  59 to undetectable truncation.
  60
  61 It gracefully degrades to being treated as L</mboxo> by MUAs
  62 unaware of the format as excessive C<E<gt>From > quoting is
  63 recognizable to humans.
  64
  65 =head2 mboxcl
  66
  67 L</mboxo> with a C<Content-Length:> header, C<From > lines
  68 remain quoted to retain readability with L</mboxo> and L</mboxrd> MUAs.
  69 However, it is easy to corrupt these files when using tools
  70 which are not aware of C<Content-Length:> and write out updates
  71 as L</mboxo>.
  72
  73 L<mutt(1)> will convert L</mboxo> and L</mboxrd> to mboxcl upon opening.
  74
  75 See also: L<https://www.jwz.org/doc/content-length.html>
  76
  77 =head2 mboxcl2
  78
  79 Like L</mboxcl>, but without C<From > any quoting.  It is wholly
  80 incompatible with MUAs which only handle L</mboxo> and/or L</mboxrd>.
  81 This is format is generated by L<mutt(1)> when writing to a new
  82 mbox.
  83
  84 =head1 MH
  85
  86 Not yet supported, locking semantics (or lack thereof) appear to
  87 make it unsuitable for parallel access.  It is widely-supported
  88 by a variety of MUAs and mailing list managers, however.
  89
  90 =head1 MMDF
  91
  92 Not yet supported, and it's unclear if current usage/support makes
  93 it worth supporting.
  94
  95 =head1 IMAP
  96
  97 Depending on the IMAP server software and configuration, IMAP
  98 servers may use any (or combination) of the aforementioned
  99 formats or a non-standard database backend.  Currently, lei
 100 uses L<Mail::IMAPClient> which has acceptable performance
 101 over low-latency links.  Performance over high-latency links
 102 is currently poor.
 103
 104 =head1 eml
 105
 106 A single raw message file.  C<eml> is not an output format for lei,
 107 but accepted by as an C<--input-format> (C<-F>) for read-only
 108 commands such as L<lei-tag(1)> and L<lei-import(1)>.
 109
 110 Since C<eml> is the suffix for the C<message/rfc822> MIME type
 111 (according to the C<mime.types> file), lei will infer the type
 112 based on the C<.eml> suffix if C<--input-format> is unspecified
 113
 114 C<.patch>-suffixed files generated by L<git-format-patch(1)>
 115 (without C<--stdout>) are C<eml> files with the addition of an
 116 mbox C<From > header.  L<lei(1)> removes C<From > lines to treat
 117 them as C<eml> when reading these for compatibility with
 118 C<git-am(1)> and similar tools.
 119
 120 =head1 COPYRIGHT
 121
 122 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 123
 124 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 125
 126 =head1 SEE ALSO
 127
 128 L<lei(1)>, L<lei-q(1)>, L<lei-convert(1)>, L<lei-overview(7)>