X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Flei-overview.pod;h=4a34bc16268e2ec5225225cbb71b59e4f0bbfafe;hb=0b15dfc58ceaecdcb1c9285c3ad55813006c8338;hp=840d011b27adb088851fe376962f93497b9a168e;hpb=f310a5054fb8e215885f0b48afac44ff32ca1d56;p=public-inbox.git

diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index 840d011b..4a34bc16 100644
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -9,16 +9,34 @@ provides some basic examples.
 
 =head1 LEI STORE
 
-L<lei-init(1)> initializes writable local storage based on
-L<public-inbox-v2-format(5)>.
+lei has writable local storage based on L<public-inbox-v2-format(5)>.
+Commands will automatically initialize the store behind the scenes if
+needed, but you can call L<lei-init(1)> directly if you want to use a
+store location other than the default C<$XDG_DATA_HOME/lei/store>.
+
+The L<lei-import(1)> command provides the primary interface for
+importing messages into the local storage.  In addition, other
+commands, such as L<lei-q(1)> and L<lei-blob(1)>, use the local store
+to memoize messages from remotes.
 
 =head2 EXAMPLES
 
 =over
 
-=item $ lei import --format=mboxrd t.mbox
+=item $ lei import mboxrd:t.mbox.gz
+
+Import the messages from a gzipped mboxrd into the local storage.
+
+=item $ lei blob 59ec517f9
+
+Show message with the git blob OID of 59ec517f9.  If a message with
+that OID isn't found, check if the current git repository has the
+blob, trying to reconstruct it from a message if needed.
 
-Import the messages from an mbox into the local storage.
+=item $ lei blob 59ec517f9 | lei tag - -F eml +kw:flagged +L:next
+
+Set the "flagged" keyword and "next" label on the message with the
+blob OID of 59ec517f9.
 
 =back
 
@@ -64,19 +82,47 @@ Search for messages whose subject includes "lei" and "skeleton".
 Do the same, but also report unmatched messages that are in the same
 thread as a matched message.
 
-=item $ lei q -t -o t.mbox -f mboxcl2 --mua=mutt s:lei s:skeleton
+=item $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton
+
+Write results to a Maildir at "mdir".  Mutt will be invoked
+to open mfolder (C<mutt -f %f>) while results are being fetched
+and written.
+
+=item $ lei q kw:flagged L:next
 
-Write mboxcl2-formatted results to t.mbox and enter mutt to view the
-file by invoking C<mutt -f %f>.
+Search for all flagged messages that also have a "next" label.
+
+=item $ lei p2q HEAD | lei q --stdin -tt -o /tmp/mdir
+
+Search for messages that have post-image git blob IDs that match those
+of the current repository's HEAD commit, writing them to the Maildir
+directory "mdir" and flagging the messages that were an exact match.
 
 =back
 
+=head1 PERFORMANCE NOTES
+
+L<Inline::C> is recommended for performance.  To enable it, create
+C<~/.cache/public-inbox/inline-c/>.
+
+If Socket::MsgHdr is installed (libsocket-msghdr-perl in Debian), the
+first invocation of lei starts a daemon, reducing the startup cost of
+for future invocations (which is particularly important for Bash
+completion).
+
+=head1 BASH COMPLETION
+
+Preliminary Bash completion for lei is provided in
+C<contrib/completion/>.  Contributions adding support for other
+shells, as well as improvements to the existing Bash completion, are
+welcome.
+
 =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://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT