treewide: update to v3 Tor onions

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

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 6f67c2777b6be145f12f29a9e0041e240ce30f51..46884aa5c875488c5a7773b75461c1ade843833f 100644 (file)
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -26,32 +26,45 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
 
 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<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.
 
 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)>.

 
 

-=for comment
-TODO: Provide description of formats?
+C<maildir> is the default for an existing directory or non-existing path.
+
+Default: C<-> (stdout)
+
+=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
 
 
 =item --pretty
 


@@ -78,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.
 
 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.
 
 
 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).
 
 
 Return all messages in the same thread as the actual match(es).
 


@@ -94,7 +116,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>.


@@ -118,7 +142,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.


@@ -133,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.
 
 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>.


@@ -150,7 +178,11 @@ C<none>.
 
 Default: fcntl,dotlock
 
 
 Default: fcntl,dotlock
 

-=item -NUMBER, -n NUMBER, --limit=NUMBER
+=item --limit=NUMBER
+
+=item -NUMBER
+
+=item -n NUMBER

 
 Limit the number of matches.
 
 
 Limit the number of matches.
 


@@ -162,26 +194,36 @@ 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.
 
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 


@@ -193,8 +235,8 @@ Default: C<auto>
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 
 
 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