doc lei overview: better explain routes into local store

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

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 0959beac385048414887135664bf16e616fd56fb..787c51bf7bdddedb0fade1080acf383b4412dc50 100644 (file)
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -6,16 +6,18 @@ lei-q - search for messages matching terms
 
 lei q [OPTIONS] TERM [TERM...]
 
-lei q [OPTIONS] --stdin
+lei q [OPTIONS] (--stdin|-)
 
 =head1 DESCRIPTION
 
 Search for messages across the lei store and externals.
 
+=for comment
 TODO: Give common prefixes, or at least a description/reference.
 
 =head1 OPTIONS
 
+=for comment
 TODO: mention curl options?
 
 =over
@@ -26,18 +28,23 @@ Read search terms from stdin.
 
 =item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
 
-Destination for results (e.g., C<path/to/Maildir> or
-C<mboxcl2:path/to/mbox>).  The format can be specified by adding a
-C<E<lt>formatE<gt>:> prefix with any of these values: C<maildir>,
+Destination for results (e.g., C<path/to/Maildir>,
+C<imaps://user@mail.example.com/INBOX.test>, or
+C<mboxcl2:path/to/mbox>).  The prefix may be a supported protocol:
+C<imap://>, C<imaps://>, C<nntp://>, or C<nntps://>.  URLs requiring
+authentication must use L<netrc(5)> and/or L<git-credential(1)> to
+fill in the username and password.
+
+The prefix can instead specify the format of the output: C<maildir>,
 C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>, C<json>, C<jsonl>, or
-C<concatjson>.
+C<concatjson>.  When a format isn't specified, it's chosen based on
+the destination.  C<json> is used for the default destination
+(stdout), and C<maildir> is used for an existing directory or
+non-existing path.
 
+=for comment
 TODO: Provide description of formats?
 
-When a format isn't specified, it's chosen based on the destination.
-C<json> is used for the default destination (stdout), and C<maildir>
-is used for an existing directory or non-existing path.
-
 Default: -
 
 =item -f FORMAT, --format=FORMAT
@@ -75,12 +82,17 @@ doesn't point to stdout, nothing otherwise.
 
 Augment output destination instead of clobbering it.
 
+=item --no-import-before
+
+Do not importing keywords before writing to an existing output
+destination.
+
 =item -t, --threads
 
 Return all messages in the same thread as the actual match(es).
 
 Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
-on messages which were actual messages.  This is useful to distinguish
+on messages which were actual matches.  This is useful to distinguish
 messages which were direct hits from messages which were merely part
 of the same thread.
 
@@ -94,6 +106,7 @@ C<none>.
 
 Default: C<content>
 
+=for comment
 TODO: Provide description of strategies?
 
 =item --[no-]remote
@@ -130,6 +143,18 @@ multiple times, in which case the search uses only the specified set.
 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 option applies to C<--include>, C<--exclude>, and C<--only>.
 
+=item --no-import-remote
+
+Disable the default behavior of memoizing remote messages into the
+local store.
+
+=item --lock
+
+L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
+C<none>.
+
+Default: fcntl,dotlock
+
 =item -NUMBER, -n NUMBER, --limit=NUMBER
 
 Limit the number of matches.