lei p2q: document --uri, add examples

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

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index bf7a5f70f9d5db68278466f68b5b5e29e278d575..574c12eb9d3a36883063fc5a05c6b793cec2698c 100644 (file)
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -10,7 +10,7 @@ lei q [OPTIONS] (--stdin|-)
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 

-Search for messages across the lei store and externals.
+Search for messages across the lei/store and externals.

 
 =for comment
 TODO: Give common prefixes, or at least a description/reference.
 
 =for comment
 TODO: Give common prefixes, or at least a description/reference.


@@ -26,6 +26,10 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
 
 Read search terms from stdin.
 

+=item --no-save
+
+Do not save the search for L<lei-up(1)>.
+

 =item --output=MFOLDER
 
 =item -o MFOLDER
 =item --output=MFOLDER
 
 =item -o MFOLDER


@@ -39,7 +43,7 @@ Destination for results (e.g., C</tmp/results-Maildir>,
 C<imaps://user@mail.example.com/INBOX.test>, or
 C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
 C<imap://> or C<imaps://>.  URLs requiring
 C<imaps://user@mail.example.com/INBOX.test>, or
 C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
 C<imap://> or C<imaps://>.  URLs requiring

-authentication must use L<netrc(5)> and/or L<git-credential(1)> to
+authentication use L<git-credential(1)> to

 fill in the username and password.
 
 A prefix can specify the format of the output: C<maildir>,
 fill in the username and password.
 
 A prefix can specify the format of the output: C<maildir>,


@@ -56,7 +60,7 @@ Default: C<-> (stdout)
 
 Format of results to stdout.  This option exists as a convenient
 way to specify the format for the default stdout destination.
 
 Format of results to stdout.  This option exists as a convenient
 way to specify the format for the default stdout destination.

-C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
+C<reply>, C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,

 as are the various mbox variants described in L</--output>.
 
 When a format isn't specified, it's chosen based on the
 as are the various mbox variants described in L</--output>.
 
 When a format isn't specified, it's chosen based on the


@@ -66,6 +70,10 @@ default destination (stdout).
 Using a C<format:> prefix with the C<--output> destination is
 preferred when not writing to stdout.
 
 Using a C<format:> prefix with the C<--output> destination is
 preferred when not writing to stdout.
 

+=item --no-color
+
+Disable color (for C<-f reply> and C<-f text>).
+

 =item --pretty
 
 Pretty print C<json> or C<concatjson> output.  If stdout is opened to
 =item --pretty
 
 Pretty print C<json> or C<concatjson> output.  If stdout is opened to


@@ -99,7 +107,7 @@ Augment output destination instead of clobbering it.
 
 =item --no-import-before
 
 
 =item --no-import-before
 

-Do not importing keywords before writing to an existing output
+Do not import keywords before writing to an existing output

 destination.
 
 =item --threads
 destination.
 
 =item --threads


@@ -156,6 +164,8 @@ multiple times.
 
 =item --only=LOCATION
 
 
 =item --only=LOCATION
 

+=item -O LOCATION
+

 Use only the specified external for search.  This option may be given
 multiple times, in which case the search uses only the specified set.
 
 Use only the specified external for search.  This option may be given
 multiple times, in which case the search uses only the specified set.
 


@@ -171,7 +181,7 @@ option applies to C<--include>, C<--exclude>, and C<--only>.
 Disable the default behavior of memoizing remote messages into the
 local store.
 
 Disable the default behavior of memoizing remote messages into the
 local store.
 

-=item --lock
+=item --lock=METHOD

 
 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 C<none>.
 
 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 C<none>.


@@ -184,7 +194,9 @@ Default: fcntl,dotlock
 
 =item -n NUMBER
 
 
 =item -n NUMBER
 

-Limit the number of matches.
+Fuzzy limit the number of matches per-local external and lei/store.
+Messages added by the L<--threads> switch do not count towards this
+limit, and there is no limit on remote externals.

 
 Default: 10000
 
 
 Default: 10000
 


@@ -229,14 +241,23 @@ Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
 Default: C<auto>
 
 
 Default: C<auto>
 

+=item --proxy=PROTO://HOST[:PORT]
+

 =back
 
 =back
 

+=head1 TIPS
+
+C<-f reply> is intended to aid in turning a cover letter
+into a reply (since using C<git format-patch --in-reply-to=...>
+is tedious).  Results (including "From " lines) should be edited
+and trimmed in your favorite C<$EDITOR> before sending.
+

 =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
 


@@ -246,5 +267,5 @@ 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-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,

 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>
 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>