doc: lei-q: document SEARCH TERMS prefixes

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

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index a84fc440552e0afed795a17bd415d71271b7ecdb..fe281d7b0121945fa3df486d5509c8edcd109bbd 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,35 +26,53 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
 
 Read search terms from stdin.
 

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

 
 Warning: this clobbers and overwrites the output destination unless
 
 Warning: this clobbers and overwrites the output destination unless

-L</-a, --augment> is specified.
+L</--augment> is specified.

 
 

-Destination for results (e.g., C<path/to/Maildir>,
+Destination for results (e.g., C</tmp/results-Maildir>,

 C<imaps://user@mail.example.com/INBOX.test>, or
 C<imaps://user@mail.example.com/INBOX.test>, or

-C<mboxcl2:path/to/mbox>).  The prefix may be a supported protocol:
+C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:

 C<imap://> or C<imaps://>.  URLs requiring
 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.
 
 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>.  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.
+A prefix can specify the format of the output: C<maildir>,
+C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>.  For a description of
+mail formats, see L<lei-mail-formats(5)>.

 
 

-=for comment
-TODO: Provide description of formats?
+C<maildir> is the default for an existing directory or non-existing path.

 
 Default: C<-> (stdout)
 
 
 Default: C<-> (stdout)
 

-=item -f FORMAT, --format=FORMAT
+=item --format=FORMAT
+
+=item -f FORMAT
+
+Format of results to stdout.  This option exists as a convenient
+way to specify the format for the default stdout destination.
+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
+L</--output> destination or prefix.  C<json> is used for the
+default destination (stdout).
+
+Using a C<format:> prefix with the C<--output> destination is
+preferred when not writing to stdout.

 
 

-Format of results.  This option exists as a convenient way to specify
-the format for the default stdout destination.  Using a C<format:>
-prefix with the C<--output> destination is preferred otherwise.
+=item --no-color
+
+Disable color (for C<-f reply> and C<-f text>).

 
 =item --pretty
 
 
 =item --pretty
 


@@ -81,16 +99,20 @@ This option may be given multiple times.
 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
 doesn't point to stdout, nothing otherwise.
 
 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
 doesn't point to stdout, nothing otherwise.
 

-=item -a, --augment
+=item --augment
+
+=item -a

 
 Augment output destination instead of clobbering it.
 
 =item --no-import-before
 
 
 Augment output destination instead of clobbering it.
 
 =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.
 
 destination.
 

-=item -t, --threads
+=item --threads
+
+=item -t

 
 Return all messages in the same thread as the actual match(es).
 
 
 Return all messages in the same thread as the actual match(es).
 


@@ -102,7 +124,9 @@ of the same thread.
 TODO: Warning: this flag may become persistent and saved in
 lei/store unless an MUA unflags it!  (Behavior undecided)
 
 TODO: Warning: this flag may become persistent and saved in
 lei/store unless an MUA unflags it!  (Behavior undecided)
 

-=item -d STRATEGY, --dedupe=STRATEGY
+=item --dedupe=STRATEGY
+
+=item -d STRATEGY

 
 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 C<none>.
 
 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 C<none>.


@@ -126,7 +150,9 @@ Limit operations to those requiring network access.
 
 Don't include results from externals.
 
 
 Don't include results from externals.
 

-=item -I LOCATION, --include=LOCATION
+=item --include=LOCATION
+
+=item -I LOCATION

 
 Include specified external in search.  This option may be given
 multiple times.
 
 Include specified external in search.  This option may be given
 multiple times.


@@ -138,10 +164,14 @@ 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.
 

-=item -g, --globoff
+=item --globoff
+
+=item -g

 
 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 option applies to C<--include>, C<--exclude>, and C<--only>.
 
 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 option applies to C<--include>, C<--exclude>, and C<--only>.


@@ -151,16 +181,22 @@ 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>.
 
 Default: fcntl,dotlock
 
 
 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
+=item --limit=NUMBER
+
+=item -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
 


@@ -170,47 +206,115 @@ Shift start of search results.
 
 Default: 0
 
 
 Default: 0
 

-=item -r, --reverse
+=item --reverse
+
+=item -r

 
 Reverse the results.  Note that this applies before C<--limit>.
 
 
 Reverse the results.  Note that this applies before C<--limit>.
 

-=item -s KEY, --sort=KEY
+=item --sort=KEY
+
+=item -s KEY

 
 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 and C<docid>.
 
 Default: C<received>
 
 
 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 and C<docid>.
 
 Default: C<received>
 

-=item -v, --verbose
+=item --verbose
+
+=item -v

 
 Provide more feedback on stderr.
 
 
 Provide more feedback on stderr.
 

-=item -q, --quiet
+=item --quiet
+
+=item -q

 
 Suppress feedback messages.
 
 
 Suppress feedback messages.
 

-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks

 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
 Default: C<auto>
 
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
 Default: C<auto>
 

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

 =back
 
 =back
 

+=head1 SEARCH TERMS
+
+C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
+instances:
+
+=for comment
+AUTO-GENERATED-SEARCH-TERMS-BEGIN
+
+  s:       match within Subject  e.g. s:"a quick brown fox"
+  d:       match date-time range, git "approxidate" formats supported
+           Open-ended ranges such as `d:last.week..' and
+           `d:..2.days.ago' are supported
+  b:       match within message body, including text attachments
+  nq:      match non-quoted text within message body
+  q:       match quoted text within message body
+  n:       match filename of attachment(s)
+  t:       match within the To header
+  c:       match within the Cc header
+  f:       match within the From header
+  a:       match within the To, Cc, and From headers
+  tc:      match within the To and Cc headers
+  l:       match contents of the List-Id header
+  bs:      match within the Subject and body
+  dfn:     match filename from diff
+  dfa:     match diff removed (-) lines
+  dfb:     match diff added (+) lines
+  dfhh:    match diff hunk header context (usually a function name)
+  dfctx:   match diff context lines
+  dfpre:   match pre-image git blob ID
+  dfpost:  match post-image git blob ID
+  dfblob:  match either pre or post-image git blob ID
+  rt:      match received time, like `d:' if sender's clock was correct
+
+=for comment
+AUTO-GENERATED-SEARCH-TERMS-END
+
+Additional search prefixes which only affect the local lei/store:
+
+  L:       match the given label
+  kw:      match the given keywords
+
+See L<lei-tag(1)> for more info on labels and keywords.
+
+Most prefixes are probabilistic, meaning they support stemming
+and wildcards (C<*>).  Ranges (such as C<d:>) and boolean prefixes
+do not support stemming or wildcards.
+The upstream Xapian query parser documentation fully explains
+the query syntax: L<https://xapian.org/docs/queryparser.html>
+
+=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
 

-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>
 
 =head1 SEE ALSO
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =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>