doc: add lei-mail-sync-overview manpage

Mostly illustrating how clunky the process is :p
We'll also tweak some things in existing man pages around
mail synchronization.

diff --git a/Documentation/lei-export-kw.pod b/Documentation/lei-export-kw.pod
index cf482ca0d30764c144246d006fdd75036a0f3622..4cb673ac4d2bc0ea401201e94e83cedb8f628bdb 100644 (file)
--- a/Documentation/lei-export-kw.pod
+++ b/Documentation/lei-export-kw.pod
@@ -12,6 +12,9 @@ lei export-kw MFOLDER [MFOLDER...]
 
 C<lei export-kw> propagates keywords (e.g. C<seen>, C<answered>,
 C<flagged>, etc.) from lei/store to IMAP folders and/or Maildirs.
 
 C<lei export-kw> propagates keywords (e.g. C<seen>, C<answered>,
 C<flagged>, etc.) from lei/store to IMAP folders and/or Maildirs.

+It only works for messages lei knows about (e.g. was used as a
+C<lei q --output>, or imported via L<lei-import(1)>, or indexed
+via L<lei-index(1)>).

 
 It does not delete, write, nor modify messages themselves;
 it only sets metadata on Maildirs and IMAP folders.
 
 It does not delete, write, nor modify messages themselves;
 it only sets metadata on Maildirs and IMAP folders.

diff --git a/Documentation/lei-forget-mail-sync.pod b/Documentation/lei-forget-mail-sync.pod
index e70b4d33a33afbf40ec3574bfeca687a476e768c..29ff567118151081485360ee3889b1fe5eb180fb 100644 (file)
--- a/Documentation/lei-forget-mail-sync.pod
+++ b/Documentation/lei-forget-mail-sync.pod
@@ -9,8 +9,9 @@ lei forget-mail-sync [OPTIONS] LOCATION [LOCATION...]
 =head1 DESCRIPTION
 
 Forget synchronization information for C<LOCATION>, an IMAP or Maildir
 =head1 DESCRIPTION
 
 Forget synchronization information for C<LOCATION>, an IMAP or Maildir

-folder.  Note that this won't delete any messages stored in Git,
-leaving C<lei-index(1)> users with dangling references.
+folder.  Note that this won't delete any messages on the filesystem.
+Users using L<lei-index(1)> without L<lei-import(1)> will be left
+with dangling references in search results.

 
 =head1 CONTACT
 
 
 =head1 CONTACT
 

diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 9322dfa8d34c9ce8c628c157fc6b040a50f0ee06..25f1daf5f32f88768e763362a7cf323d61f08388 100644 (file)
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -4,7 +4,7 @@ lei-import - one-time import of messages into local store
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-lei import [OPTIONS] LOCATION [LOCATION...]
+lei import [OPTIONS] LOCATION [LOCATION...] [+L:LABEL]

 
 lei import [OPTIONS] (--stdin|-)
 
 
 lei import [OPTIONS] (--stdin|-)
 


@@ -16,8 +16,8 @@ source of messages: a directory (Maildir), a file, or a URL
 authentication use L<git-credential(1)> to
 fill in the username and password.
 
 authentication use L<git-credential(1)> to
 fill in the username and password.
 

-For a regular file, the location must have a C<E<lt>formatE<gt>:>
-prefix specifying one of the following formats: C<eml>, C<mboxrd>,
+For a regular file, the C<LOCATION> must have a C<E<lt>formatE<gt>:>
+prefix specifying one of the following formats: C<mboxrd>,

 C<mboxcl2>, C<mboxcl>, or C<mboxo>.
 
 =head1 OPTIONS
 C<mboxcl2>, C<mboxcl>, or C<mboxo>.
 
 =head1 OPTIONS


@@ -42,6 +42,29 @@ C<none>.
 
 Default: fcntl,dotlock
 
 
 Default: fcntl,dotlock
 

+=item +L:LABEL
+
+Add the given C<LABEL> to all messages imported, where C<LABEL>
+is an arbitrary user-defined value consisting of lowercase and digits.
+See L<lei-tag(1)> for more info on labels.
+
+For example, specifying C<+L:inbox> applies the C<inbox> label
+to all messages being imported.
+
+May be specified multiple times to apply multiple labels.
+
+Default: none
+
+=item +kw:KEYWORD
+
+Apply C<KEYWORD> to all messages being imported in addition
+to any per-message keywords from the store (unless C<--no-kw>
+is specified).  See L<lei-tag(1)> for more info on keywords.
+
+May be specified multiple times to apply multiple keywords.
+
+Default: none
+

 =item --no-kw
 
 Don't import message keywords (or "flags" in IMAP terminology).
 =item --no-kw
 
 Don't import message keywords (or "flags" in IMAP terminology).


@@ -73,11 +96,10 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>

 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 

-

 =head1 SEE ALSO
 
 =head1 SEE ALSO
 

-L<lei-add-external(1)>
+L<lei-index(1)>

diff --git a/Documentation/lei-index.pod b/Documentation/lei-index.pod
index 9e72026351a1921f8239bbfe88b99089fedb588f..f8ff69509dcf73d6dd0af5fb6d3d2f0b3ebf0b93 100644 (file)
--- a/Documentation/lei-index.pod
+++ b/Documentation/lei-index.pod
@@ -20,6 +20,9 @@ Combined with L<lei-q(1)>, C<lei index> allows Maildir users to
 have similar functionality to L<mairix(1)> by not duplicating
 messages into C<lei/store>.
 
 have similar functionality to L<mairix(1)> by not duplicating
 messages into C<lei/store>.
 

+Occasional invocations of C<lei-refresh-mail-sync --all=local>
+are recommended to keep indexed messages retrievable.
+

 =head1 OPTIONS
 
 =over
 =head1 OPTIONS
 
 =over


@@ -58,4 +61,4 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 

-L<lei-store-format(5)>, L<lei-import(1)>
+L<lei-refresh-mail-sync(1)>, L<lei-store-format(5)>, L<lei-import(1)>

diff --git a/Documentation/lei-ls-label.pod b/Documentation/lei-ls-label.pod
index 41aa030d993200b5c615e6fc5edc331f382aedc5..8342705a6cf64b4845fde5b03c41ff6c44cae60a 100644 (file)
--- a/Documentation/lei-ls-label.pod
+++ b/Documentation/lei-ls-label.pod
@@ -9,6 +9,7 @@ lei ls-label [OPTIONS]
 =head1 DESCRIPTION
 
 List all known message labels ("mailboxes" in JMAP terminology).
 =head1 DESCRIPTION
 
 List all known message labels ("mailboxes" in JMAP terminology).

+This is handy for writing L<lei-import(1)> invocations.

 
 =head1 OPTIONS
 
 
 =head1 OPTIONS
 

diff --git a/Documentation/lei-ls-mail-source.pod b/Documentation/lei-ls-mail-source.pod
index 926bbe2c02f674698ded17705c8c591fbcaa0147..59d14afe688068a250c881a589e5a0b869dc1e96 100644 (file)
--- a/Documentation/lei-ls-mail-source.pod
+++ b/Documentation/lei-ls-mail-source.pod
@@ -9,6 +9,8 @@ lei ls-mail-source [OPTIONS] URL
 =head1 DESCRIPTION
 
 List information about the IMAP or NNTP mail source at C<URL>.
 =head1 DESCRIPTION
 
 List information about the IMAP or NNTP mail source at C<URL>.

+This command populates the cache used for Bash shell completion
+and is handy for writing L<lei-import(1)> invocations.

 
 =head1 OPTIONS
 
 
 =head1 OPTIONS
 


@@ -48,11 +50,10 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>

 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 

-

 =head1 SEE ALSO
 
 L<lei-import(1)>
 =head1 SEE ALSO
 
 L<lei-import(1)>

diff --git a/Documentation/lei-ls-watch.pod b/Documentation/lei-ls-watch.pod
index b1681ee457827372b550637c3b9ee6ce989a0af4..8063d34d32733a389af721c0811871ecd3f0431b 100644 (file)
--- a/Documentation/lei-ls-watch.pod
+++ b/Documentation/lei-ls-watch.pod
@@ -8,7 +8,8 @@ lei ls-watch
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 

-List locations that lei is configured to watch.
+List locations that lei is configured to watch.  This command is
+incomplete, mail-sync locations are implicitly watched.

 
 =head1 CONTACT
 
 
 =head1 CONTACT
 

diff --git a/Documentation/lei-mail-formats.pod b/Documentation/lei-mail-formats.pod
index 3c37c88046b6c508eb0094e1c0c813ddeb450058..930c5d7660ea03e2113f7dc027977ceb76f7e5a1 100644 (file)
--- a/Documentation/lei-mail-formats.pod
+++ b/Documentation/lei-mail-formats.pod
@@ -96,7 +96,10 @@ it worth supporting.
 
 Depending on the IMAP server software and configuration, IMAP
 servers may use any (or combination) of the aforementioned
 
 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.
+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
 
 
 =head1 eml
 

diff --git a/Documentation/lei-mail-sync-overview.pod b/Documentation/lei-mail-sync-overview.pod
new file mode 100644 (file)
index 0000000..e30674b
--- /dev/null
+++ b/Documentation/lei-mail-sync-overview.pod
@@ -0,0 +1,53 @@
+=head1 NAME
+
+lei - an overview of lei mail synchronization
+
+=head1 DESCRIPTION
+
+L<lei(1)> provides several plumbing-level commands to synchronize
+mail and keywords (flags) between lei/store and existing IMAP
+and Maildir stores.  Nothing documented in this manpage is required
+for day-to-day use against externals.
+
+Mail and keyword synchronization is currently a clunky process.
+Future work will be done to improve it and add IMAP IDLE support.
+
+=head1 TYPICAL WORKFLOW
+
+  # import mail from a user's IMAP inbox and give it the "inbox" label:
+  lei import +L:inbox imaps://user@example.com/INBOX
+
+  # dump "inbox" labeled files from the past week to a Maildir
+  lei q L:inbox rt:last.week.. -o /tmp/results
+
+  # open /tmp/results in your favorite mail agent.  If inotify or kevent
+  # works, keyword changes (e.g. marking messages as `seen') are
+  # synchronized automatically.
+
+  # If the inotify queue overflows, or if lei-daemon crashes,
+  # "lei index" will tell lei about keyword changes:
+  lei index /tmp/results
+
+  # Optional: cleanup stale entries from mail_sync.sqlite3
+  lei refresh-mail-sync /tmp/results
+
+  # to export keyword changes back to IMAP
+  lei export-kw imaps://user@example.com/INBOX
+
+=head1 CONTACT
+
+Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
+
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
+
+=head1 COPYRIGHT
+
+Copyright all contributors L<mailto:meta@public-inbox.org>
+
+License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<lei-import(1)>, L<lei-q(1)>, L<lei-index(1)>,
+L<lei-refresh-mail-sync(1)>, L<lei-export-kw(1)>

diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index 99fd6ef72174e5759669a4131f9563d04e2ee0bb..7095b504cdb8c84ed98b75f61d4f889a4fda71b7 100644 (file)
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -4,8 +4,8 @@ lei - an overview of lei
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 

-L<lei(1)> is a local email interface for public-inbox.  This document
-provides some basic examples.
+L<lei(1)> is a local email interface for public-inbox and personal mail.
+This document provides some basic examples.

 
 =head1 LEI STORE
 
 
 =head1 LEI STORE
 


@@ -49,6 +49,11 @@ For existing local paths, the external needs to be indexed with
 L<public-inbox-index(1)> (in the case of a regular inbox) or
 L<public-inbox-extindex(1)> (in the case of an external index).
 
 L<public-inbox-index(1)> (in the case of a regular inbox) or
 L<public-inbox-extindex(1)> (in the case of an external index).
 

+=head1 SYNCHRONIZATION
+
+lei currently has primitive mail synchronization abilities;
+see L<lei-mail-sync-overview(7)> for more details.
+

 =head2 EXAMPLES
 
 =over
 =head2 EXAMPLES
 
 =over


@@ -154,3 +159,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>

+
+=head1 SEE ALSO
+
+L<lei-mail-sync-overview(7)>

diff --git a/Documentation/lei-tag.pod b/Documentation/lei-tag.pod
index b2509ba4ee26a75883b95dab2d065a0032e935ba..8cb9e736b6e74acd9924dd0339edec3ec0490987 100644 (file)
--- a/Documentation/lei-tag.pod
+++ b/Documentation/lei-tag.pod
@@ -43,6 +43,26 @@ Suppress feedback messages.
 
 =back
 
 
 =back
 

+=head1 LABELS
+
+Labels are user-defined values analogous to IMAP/JMAP mailbox
+names.  They must only contain lowercase characters, digits, and
+a limited amount of punctuation (e.g. C<.>, C<->, C<@>).
+
+Messages may have multiple labels.
+
+=head1 KEYWORDS
+
+Keywords are "flags" in Maildir and IMAP terminology.
+Common keywords include: C<seen>, C<answered>, C<flagged>, and
+C<draft>, though C<forwarded>, C<phishing>, C<junk>, and C<notjunk>
+are also supported.
+
+When writing to various mboxes, the common keywords will be
+mapped to the C<Status> and C<X-Status> headers.
+
+Messages may have multiple keywords.
+

 =head1 CONTACT
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 =head1 CONTACT
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>


@@ -56,7 +76,6 @@ Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 

-

 =head1 SEE ALSO
 
 L<lei-add-external(1)>
 =head1 SEE ALSO
 
 L<lei-add-external(1)>

diff --git a/Documentation/lei.pod b/Documentation/lei.pod
index 24a585daf24c7ed747851d6ce024fcd926555fc0..f01f506af359c1a476dc9ad01f6208389e847a70 100644 (file)
--- a/Documentation/lei.pod
+++ b/Documentation/lei.pod
@@ -106,7 +106,7 @@ Other subcommands include
 
 =item * L<lei-daemon-pid(1)>
 
 
 =item * L<lei-daemon-pid(1)>
 

-=item * lei-forget-mail-sync(1)
+=item * L<lei-forget-mail-sync(1)>

 
 =item * L<lei-mail-diff(1)>
 
 
 =item * L<lei-mail-diff(1)>
 


@@ -145,7 +145,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>

 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 

diff --git a/MANIFEST b/MANIFEST
index 9fd979ef02fb86731a5f814e5bb45a3b423dee79..1e8f60fb41da05bb75ec8fe933473e9c70f4ec41 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -47,6 +47,7 @@ Documentation/lei-ls-search.pod
 Documentation/lei-ls-watch.pod
 Documentation/lei-mail-diff.pod
 Documentation/lei-mail-formats.pod
 Documentation/lei-ls-watch.pod
 Documentation/lei-mail-diff.pod
 Documentation/lei-mail-formats.pod

+Documentation/lei-mail-sync-overview.pod

 Documentation/lei-overview.pod
 Documentation/lei-p2q.pod
 Documentation/lei-q.pod
 Documentation/lei-overview.pod
 Documentation/lei-p2q.pod
 Documentation/lei-q.pod

diff --git a/Makefile.PL b/Makefile.PL
index b3ac59be32eed944cca46c0d9e6f40c5e17a2d2f..8c8c0235f35bc38320f5dd0478bfa9439afa08e9 100644 (file)
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -1,5 +1,5 @@
 #!/usr/bin/perl -w
 #!/usr/bin/perl -w

-# Copyright (C) 2013-2021 all contributors <meta@public-inbox.org>
+# Copyright (C) all contributors <meta@public-inbox.org>

 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 use strict;
 use ExtUtils::MakeMaker;
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 use strict;
 use ExtUtils::MakeMaker;


@@ -57,7 +57,7 @@ $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
                public-inbox-v2-format public-inbox-extindex-format
                lei-mail-formats lei-store-format
                ) ];
                public-inbox-v2-format public-inbox-extindex-format
                lei-mail-formats lei-store-format
                ) ];

-$v->{-m7} = [ qw(lei-overview lei-security
+$v->{-m7} = [ qw(lei-mail-sync-overview lei-overview lei-security

                public-inbox-overview public-inbox-tuning
                public-inbox-glossary) ];
 $v->{-m8} = [ qw(public-inbox-daemon lei-daemon) ];
                public-inbox-overview public-inbox-tuning
                public-inbox-glossary) ];
 $v->{-m8} = [ qw(public-inbox-daemon lei-daemon) ];