From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00 shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id A3ABA1F934 for ; Wed, 31 Mar 2021 00:41:09 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH 1/2] doc: add lei-mail-formats(5) manpage Date: Wed, 31 Mar 2021 00:41:08 +0000 Message-Id: <20210331004109.32610-2-e@80x24.org> In-Reply-To: <20210331004109.32610-1-e@80x24.org> References: <20210331004109.32610-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: While plenty of online documentation exists, it's good to have a locally-available summary for users to look at offline. Fix a URL in Watch.pm while we're at it, too. --- Documentation/lei-mail-formats.pod | 101 +++++++++++++++++++++++++++++ MANIFEST | 1 + Makefile.PL | 4 +- lib/PublicInbox/Watch.pm | 2 +- 4 files changed, 106 insertions(+), 2 deletions(-) create mode 100644 Documentation/lei-mail-formats.pod diff --git a/Documentation/lei-mail-formats.pod b/Documentation/lei-mail-formats.pod new file mode 100644 index 00000000..8accedb4 --- /dev/null +++ b/Documentation/lei-mail-formats.pod @@ -0,0 +1,101 @@ +=head1 NAME + +lei-mail-formats - description of mail formats supported by lei + +=head1 DESCRIPTION + +L 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 and +L + +=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), +they require the least amount of space while offering good +read-only performance. + +Keyword updates (C and/or C headers) +generally require rewriting the entire mbox. + +See also: +L, +L + +=head2 mboxo + +The traditional BSD format. It quotes C to CFrom >, +but lines already beginning with CFrom > do not get quoted, +thus automatic reversibility is not guaranteed. MUAs which favor +L or L may convert these automatically to their +preferred format. + +Truncation is undetectable unless compressed with gzip or similar. + +=head2 mboxrd + +An evolution of L, but quotes C lines prefixed +with any number of C> characters and is thus fully +reversible. + +This format is emitted by L with gzip. +It is supported by L since git 2.10. + +As with uncompressed L, uncompressed mboxrd are vulnerable +to undetectable truncation. + +It gracefully degrades to being treated as L by MUAs +unaware of the format as excessive CFrom > quoting is +recognizable to humans. + +=head2 mboxcl + +L with a C header, C lines +remain quoted to retain readability with L and L MUAs. +However, it is easy to corrupt these files when using tools +which are not aware of C and write out updates +as L. + +L will convert L and L to mboxcl upon opening. + +See also: L + +=head2 mboxcl2 + +Like L, but without C any quoting. It is wholly +incompatible with MUAs which only handle L and/or L. +This is format is generated by L when writing to a new +mbox. + +=head1 MH + +Not yet supported, locking semantics (or lack thereof) appear to +make it unsuitable for parallel access. + +=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. + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, L diff --git a/MANIFEST b/MANIFEST index f3cb0147..49d273fc 100644 --- a/MANIFEST +++ b/MANIFEST @@ -31,6 +31,7 @@ Documentation/lei-import.pod Documentation/lei-init.pod Documentation/lei-ls-external.pod Documentation/lei-ls-label.pod +Documentation/lei-mail-formats.pod Documentation/lei-overview.pod Documentation/lei-p2q.pod Documentation/lei-q.pod diff --git a/Makefile.PL b/Makefile.PL index 27b49c53..feb89ec1 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -48,7 +48,9 @@ $v->{-m1} = [ map { lei-forget-external lei-import lei-init lei-ls-external lei-ls-label lei-tag lei-p2q lei-q)]; $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format - public-inbox-v2-format public-inbox-extindex-format) ]; + public-inbox-v2-format public-inbox-extindex-format + lei-mail-formats + ) ]; $v->{-m7} = [ qw(lei-overview public-inbox-overview public-inbox-tuning public-inbox-glossary) ]; $v->{-m8} = [ qw(public-inbox-daemon) ]; diff --git a/lib/PublicInbox/Watch.pm b/lib/PublicInbox/Watch.pm index 4fbc9640..05956cbb 100644 --- a/lib/PublicInbox/Watch.pm +++ b/lib/PublicInbox/Watch.pm @@ -2,7 +2,7 @@ # License: AGPL-3.0+ # # ref: https://cr.yp.to/proto/maildir.html -# httsp://wiki2.dovecot.org/MailboxFormat/Maildir +# https://wiki2.dovecot.org/MailboxFormat/Maildir package PublicInbox::Watch; use strict; use v5.10.1;