X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Flei-q.pod;h=46884aa5c875488c5a7773b75461c1ade843833f;hb=0b15dfc58ceaecdcb1c9285c3ad55813006c8338;hp=e307e0205f932b0a7051b4379ccf50e8154af7d1;hpb=82691a35fcf3b8945539084a029722b3458d72c8;p=public-inbox.git diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod index e307e020..46884aa5 100644 --- a/Documentation/lei-q.pod +++ b/Documentation/lei-q.pod @@ -6,29 +6,65 @@ lei-q - search for messages matching terms lei q [OPTIONS] TERM [TERM...] +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 -=item -o PATH, --output=PATH, --mfolder=PATH +=item --stdin + +Read search terms from stdin. + +=item --output=MFOLDER + +=item -o MFOLDER + +=item --mfolder=MFOLDER -Destination for results (e.g., C or - for stdout). +Warning: this clobbers and overwrites the output destination unless +L is specified. -Default: - +Destination for results (e.g., C, +C, or +C). The prefix may be a supported protocol: +C or C. URLs requiring +authentication must use L and/or L to +fill in the username and password. -=item -f FORMAT, --format=FORMAT +A prefix can specify the format of the output: C, +C, C, C, C. For a description of +mail formats, see L. -Format of results: C, C, C, C, -C, C, C, or C. The default format -used depends on C<--output>. +C is the default for an existing directory or non-existing path. -TODO: Provide description of formats? +Default: C<-> (stdout) + +=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, C, C, or C are all supported, +as are the various mbox variants described in L. + +When a format isn't specified, it's chosen based on the +L destination or prefix. C is used for the +default destination (stdout). + +Using a C prefix with the C<--output> destination is +preferred when not writing to stdout. =item --pretty @@ -36,28 +72,60 @@ Pretty print C or C output. If stdout is opened to a tty and used as the C<--output> destination, C<--pretty> is enabled by default. -=item --mua-cmd=COMMAND, --mua=COMMAND +=item --mua=COMMAND A command to run on C<--output> Maildir or mbox (e.g., C). For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can be abbreviated to the name of the program: C, C, C, or C. +=item --alert=COMMAND[,COMMAND...] + +Run C after writing to output. C<:WINCH> indicates to send +C to the C<--mua> process. C<:bell> indicates to print a +bell code. Any other value is interpreted as a command to execute as +is. + +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 --augment +=item -a + Augment output destination instead of clobbering it. -=item -t, --thread +=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). -=item -d STRATEGY, --dedupe=STRATEGY +Using this twice (C<-tt>) sets the C (AKA "important") +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. + +TODO: Warning: this flag may become persistent and saved in +lei/store unless an MUA unflags it! (Behavior undecided) + +=item --dedupe=STRATEGY + +=item -d STRATEGY Strategy for deduplicating messages: C, C, C, or C. Default: C +=for comment TODO: Provide description of strategies? =item --[no-]remote @@ -74,7 +142,47 @@ Limit operations to those requiring network access. Don't include results from externals. -=item -NUMBER, -n NUMBER, --limit=NUMBER +=item --include=LOCATION + +=item -I LOCATION + +Include specified external in search. This option may be given +multiple times. + +=item --exclude=LOCATION + +Exclude specified external from search. This option may be given +multiple times. + +=item --only=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. + +=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>. + +=item --no-import-remote + +Disable the default behavior of memoizing remote messages into the +local store. + +=item --lock + +L locking method(s) to use: C, C, C or +C. + +Default: fcntl,dotlock + +=item --limit=NUMBER + +=item -NUMBER + +=item -n NUMBER Limit the number of matches. @@ -86,22 +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, C, and C. Default: C -=item -v, --verbose +=item --verbose + +=item -v Provide more feedback on stderr. -=item --torsocks=auto|no|yes, --no-torsocks +=item --quiet + +=item -q + +Suppress feedback messages. + +=item --torsocks=auto|no|yes + +=item --no-torsocks Whether to wrap L and L commands with torsocks. @@ -113,8 +235,8 @@ Default: C Feedback welcome via plain-text mail to L -The mail archives are hosted at L -and L +The mail archives are hosted at L and +L =head1 COPYRIGHT @@ -124,4 +246,5 @@ License: AGPL-3.0+ L =head1 SEE ALSO -L +L, +L