X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Flei-q.pod;h=46884aa5c875488c5a7773b75461c1ade843833f;hb=0b15dfc58ceaecdcb1c9285c3ad55813006c8338;hp=446a82c61fd478f92a7487abbb87b9953033a25d;hpb=804707a2ec00a06a8fc2899ca31f23b87754ea89;p=public-inbox.git

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 446a82c6..46884aa5 100644
--- 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
@@ -24,31 +26,45 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
-=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
+=item --output=MFOLDER
 
-Destination for results (e.g., C<path/to/Maildir>,
+=item -o MFOLDER
+
+=item --mfolder=MFOLDER
+
+Warning: this clobbers and overwrites the output destination unless
+L</--augment> is specified.
+
+Destination for results (e.g., C</tmp/results-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
+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
 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)>.
+
+C<maildir> is the default for an existing directory or non-existing path.
+
+Default: C<-> (stdout)
 
-TODO: Provide description of formats?
+=item --format=FORMAT
 
-Default: -
+=item -f FORMAT
 
-=item -f FORMAT, --format=FORMAT
+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,
+as are the various mbox variants described in L</--output>.
 
-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.
+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.
 
 =item --pretty
 
@@ -75,11 +91,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.
 
-=item -a, --augment
+=item --augment
+
+=item -a
 
 Augment output destination instead of clobbering it.
 
-=item -t, --threads
+=item --no-import-before
+
+Do not importing keywords before writing to an existing output
+destination.
+
+=item --threads
+
+=item -t
 
 Return all messages in the same thread as the actual match(es).
 
@@ -91,13 +116,16 @@ of the same thread.
 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>.
 
 Default: C<content>
 
+=for comment
 TODO: Provide description of strategies?
 
 =item --[no-]remote
@@ -114,7 +142,9 @@ Limit operations to those requiring network access.
 
 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.
@@ -129,7 +159,9 @@ multiple times.
 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>.
@@ -146,7 +178,11 @@ C<none>.
 
 Default: fcntl,dotlock
 
-=item -NUMBER, -n NUMBER, --limit=NUMBER
+=item --limit=NUMBER
+
+=item -NUMBER
+
+=item -n NUMBER
 
 Limit the number of matches.
 
@@ -158,26 +194,36 @@ Shift start of search results.
 
 Default: 0
 
-=item -r, --reverse
+=item --reverse
+
+=item -r
 
 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>
 
-=item -v, --verbose
+=item --verbose
+
+=item -v
 
 Provide more feedback on stderr.
 
-=item -q, --quiet
+=item --quiet
+
+=item -q
 
 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.
 
@@ -189,8 +235,8 @@ Default: C<auto>
 
 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