doc: lei-overview: add CAVEATS section

[public-inbox.git] / Documentation / lei-overview.pod

diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index 70dbf2b52a29cbcab15dd2f93bd934379d30d4a2..99fd6ef72174e5759669a4131f9563d04e2ee0bb 100644 (file)
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -33,7 +33,7 @@ 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.
 
 that OID isn't found, check if the current git repository has the
 blob, trying to reconstruct it from a message if needed.
 

-=item $ lei blob 59ec517f9 | lei tag - -F eml +kw:flagged +L:next
+=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.
 
 Set the "flagged" keyword and "next" label on the message with the
 blob OID of 59ec517f9.


@@ -82,7 +82,7 @@ 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.
 
 Do the same, but also report unmatched messages that are in the same
 thread as a matched message.
 

-=item $ lei q -t -o mdir --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
 
 Write results to a Maildir at "mdir".  Mutt will be invoked
 to open mfolder (C<mutt -f %f>) while results are being fetched


@@ -92,23 +92,37 @@ and written.
 
 Search for all flagged messages that also have a "next" label.
 
 
 Search for all flagged messages that also have a "next" label.
 

-=item $ lei p2q HEAD | lei q --stdin -tt -o mdir
+=item $ lei p2q HEAD | lei q -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.
 
 
 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.
 

+=item $ git show -s HEAD | lei lcat
+
+Display a local message for the public-inbox link contained in a
+commit message.
+
+=item $ lei q -f text m:MESSAGE-ID | lei rediff -U5
+
+Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
+diff with five context lines.  Unless C<--git-dir> is specified, this
+requires the current working directory to be within the associated
+code repository.
+

 =back
 
 =head1 PERFORMANCE NOTES
 
 =back
 
 =head1 PERFORMANCE NOTES
 

-L<Inline::C> is recommended for performance.  To enable it, create
-C<~/.cache/public-inbox/inline-c/>.
+L<Inline::C> is required, lei runs as a background daemon to reduce
+startup costs and can provide real-time L<kqueue(2)>/L<inotify(7)>
+Maildir monitoring.  L<IO::KQueue> (p5-IO-KQueue on FreeBSD) and
+L<Linux::Inotify2> (liblinux-inotify2-perl and perl-Linux-Inotify2 in
+.deb and .rpm-based distros, respectively) are recommended.

 
 

-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).
+L<Socket::MsgHdr> is optional (libsocket-msghdr-perl in Debian),
+and further improves startup performance.  Its effect is most felt
+when using shell completion.

 
 =head1 BASH COMPLETION
 
 
 =head1 BASH COMPLETION
 


@@ -117,15 +131,26 @@ C<contrib/completion/>.  Contributions adding support for other
 shells, as well as improvements to the existing Bash completion, are
 welcome.
 
 shells, as well as improvements to the existing Bash completion, are
 welcome.
 

+=head1 UPGRADING
+
+Since lei runs as a daemon, L<lei-daemon-kill(1)> is required to kill
+the daemon so it can load new code.  It will be restarted with the
+next invocation of any lei command.
+
+=head1 CAVEATS
+
+IMAP and NNTP client performance is poor on high-latency connections.
+It will hopefully be fixed in 2022.
+

 =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>
 

-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
 
 
 =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>