unofficial mirror of
 help / color / mirror / Atom feed
From: Eric Wong <>
Subject: [PATCH 1/2] doc: add lei-mail-formats(5) manpage
Date: Wed, 31 Mar 2021 00:41:08 +0000	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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 while we're at it, too.
 Documentation/lei-mail-formats.pod | 101 +++++++++++++++++++++++++++++
 MANIFEST                           |   1 +
 Makefile.PL                        |   4 +-
 lib/PublicInbox/           |   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
+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<> and
+=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:
+=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
+This format is emitted by L<PublicInbox::WWW(3pm)> with gzip.
+It is supported by L<git-am(1)> since git 2.10.
+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<>
+=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
+=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.
+Copyright 2021 all contributors L<>
+License: AGPL-3.0+ L<>
+=head1 SEE ALSO
+L<lei(1)>, L<lei-q(1)>, L<lei-convert(1)>, L<lei-overview(7)>
diff --git a/MANIFEST b/MANIFEST
index f3cb0147..49d273fc 100644
@@ -31,6 +31,7 @@ Documentation/lei-import.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/ b/lib/PublicInbox/
index 4fbc9640..05956cbb 100644
--- a/lib/PublicInbox/
+++ b/lib/PublicInbox/
@@ -2,7 +2,7 @@
 # License: AGPL-3.0+ <>
 # ref:
-#	httsp://
 package PublicInbox::Watch;
 use strict;
 use v5.10.1;

  reply	other threads:[~2021-03-31  0:41 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-03-31  0:41 [PATCH 0/2] lei doc: mail formats Eric Wong
2021-03-31  0:41 ` Eric Wong [this message]
2021-03-31  3:15   ` [PATCH 1/2] doc: add lei-mail-formats(5) manpage Kyle Meyer
2021-03-31  0:41 ` [PATCH 2/2] doc: lei-overview: favor Maildir for mutt examples Eric Wong

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \
    --subject='Re: [PATCH 1/2] doc: add lei-mail-formats(5) manpage' \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

unofficial mirror of

This inbox may be cloned and mirrored by anyone:

	git clone --mirror

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 meta meta/ \
	public-inbox-index meta

Example config snippet for mirrors.
Newsgroups are available over NNTP:

AGPL code for this site: git clone http://ou63pmih66umazou.onion/public-inbox.git