about summary refs log tree commit homepage
path: root/Documentation/lei-q.pod
DateCommit message (Collapse)
2024-04-12lei q: support --thread-id=$MSGID || -T $MSGID
This adds support for the "POST /$INBOX/$MSGID/?x=m?q=..." added last year to support per-thread searches 764035c83 (www: support POST /$INBOX/$MSGID/?x=m&q=, 2023-03-30) This only supports instances of public-inbox since 764035c83, but unfortunately there hasn't been a release since then.
2024-02-14doc: fix formatting for CLI switch aliases
`=item' elements in Pod need to be surrounded by empty lines. It's an unfortunate waste of vertical space, but Pod is still better than *roff and usually available out-of-the-box.
2023-11-29lei q: fix --no-import-before completion + docs
--no-import-before skips importing entire messages, not just keywords, so it can cause permanent data loss if -o is pointed to precious data.
2023-10-17doc: lei-q: drop stale TODO comment (fixed in 1f1b1f0e22f7)
Fixes: 1f1b1f0e22f7 ("doc: lei-q: document SEARCH TERMS prefixes")
2023-10-17doc: fix some typos and grammar
[ew: leave install/README unchanged pending wording changes]
2023-06-15doc: lei q: document v2:$INBOX_DIR output format
This has been supported in every lei release, actually.
2023-02-27doc: note "lei q -tt" is broken with HTTP(S) remotes
I'm still trying to decide how to handle HTTP(S) remotes properly... Link: https://public-inbox.org/meta/20230226170931.M947721@dcvr/
2022-11-16lei q|up: limit default write --jobs for IMAP(S)
Eric Wong <e@80x24.org> wrote: > Thanks for confirming things work as intended. I think the > default should be clamped, though... 15 seems a bit high for > smaller IMAP servers *shrug* --------8<------- Subject: [PATCH] lei q|up: limit default write --jobs for IMAP(S) IMAP(S) servers often limit per-user connections, so avoid bumping into limits to improve the out-of-the-box experience. 4 seems like a conservative default, since we already chose that number for remote HTTP(S) endpoints. Link: https://public-inbox.org/meta/20220910201958.GA12212@dcvr/
2022-09-09doc: document --jobs for `lei q' and `lei up'
These may be helpful for users on slow disks or have IMAP server limitations.
2022-08-11doc: spell out "PROTOCOL" in examples
"PROTO" is probably ambiguous, and we'll use the same terminology as used in curl(1) documentation.
2022-06-22doc: lei-q: regenerate for patchid: help
2021-11-04doc: add more 3rd-party refs, use Debian manpages for xapian
curl, torsocks, and gitglossary manpages are all newly referenced, so make sure they're linkified properly in HTML. We'll be using Debian's manpages as an ad-free, Tor-accessible host for manpages as a fallback since hosting manpages for all 3rd-party projects we reference doesn't scale.
2021-11-03doc: lei-q: document SEARCH TERMS prefixes
The new Documentation/common.perl file will be used for all manpages in the future.
2021-10-14lei: -d (--dir) and -O (only) shortcuts
`-d' seems like a non-brainer for --dir with inspect. I find myself using `--only' a bit, too, and `-O' seems like a reasonable shortcut for it.
2021-09-21lei q: improve --limit behavior and progress
Avoid slurping gigantic (e.g. 100000) result sets into a single response if a giant limit is specified, and instead use 10000 as a window for the mset with a given offset. We'll also warn and hint towards about the --limit= switch when the estimated result set is larger than the default limit.
2021-09-14doc: update authentication notes for lei
~/.netrc isn't used by default any more, and I'm not sure it's worthwhile to document the --netrc switch since it's rare for non-FTP clients to support. Followup-to: 9d11ed460ce113dd ("lei: do not read ~/.netrc by default") Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
2021-09-11lei q|lcat: support "-f reply" output format
When composing replies in "git format-patch" cover letters, I'd been relying on "lei q -f text ...", but that still requires several steps to make it suitable for composing a reply: * s/^/> / to quote the body * drop existing In-Reply-To+References * s/^Message-ID:/In-Reply-To:/; * add an attribute line ... "lei q -f reply" takes care of most of that and users will only have to trim "From " lines, unnecessary results and over-quoted text (and trimming is likely less error-prone than doing all the steps above manually). This should also be a good replacement for "git format-patch --in-reply-to=...", since copying long Message-IDs can be error-prone (and this lets you include quoted text in replies).
2021-08-19lei q: make --save the default
Since "lei up" is more often useful than not and incurs neglible overhead; enable --save by default and allow --no-save to work. This also fixes a long-standing when overwriting --output destinations with saved searches: dedupe data from previous searches are reset and no longer influences the new (changed) search, so results no longer go missing if two sequential invocations of "lei q --save" point to the same --output.
2021-05-17doc lei: update manpages with new options
2021-05-17doc lei: add manpages for new commands
[ew: MANIFEST: s/lei-cat/lei-lcat/]
2021-05-17doc lei q: add missing value for --lock
2021-05-17doc lei q: fix a typo
2021-05-04treewide: update to v3 Tor onions
v2 onions are insecure, deprecated and going away. v3 names are unfortunately longer and more difficult to remember, but should be more resistant to attack than v2 ones.
2021-04-28doc: lei q: split --output and --format, note "text"
I guess --format makes sense for stdout, after all; and I'm enjoying "-f text" quite a bit, so far.
2021-04-28doc: lei q: split =item aliases onto separate lines
It makes L</--augment> look nicer without resorting to L<--augment|/-a, --augment> and similarly verbose nastiness. Having each option as a separate =item (with a blank line in between each =item) seems to be the preferred style used within Perl core documentation (I used perlrun.pod as an example), so we'll follow Perl core style, here. This needs to be done for other manpages, at some point...
2021-04-28doc: lei: use /tmp for search results pathnames
This drives the point home about results being volatile and discardable.
2021-03-29doc: lei q: clarify default output as stdout
Seeing a plain "-" may be confusing, especially when we also support it for --stdin. Use the C<> POD directive to denote it as code, too.
2021-03-29doc: lei q: add warning for --output clobbering
The behavior matching mairix still frightens me a bit when it comes to supporting new users. On the other hand, I've rarely ever used --augment with mairix, so I still think the current (dangerous) behavior makes sense in the context of search results.
2021-03-29doc: lei q: drop NNTP from --output description
We only support NNTP as inputs for convert, import, and mark|tag. I'm not sure if supporting NNTP output is worth it, nor do we have a good way to test it.
2021-03-29doc lei: update manpages with new options
2021-03-29doc lei: don't render most to-do comments
The lei manpages have a number of to-dos, but with the exception of the lei-q's -tt warning, none of them seem worth displaying to the reader (and some might not be worth addressing at all).
2021-03-29doc lei: note --stdin shortcut in synopses
2021-03-29doc lei-q: fix typo in -tt description
2021-02-27doc: lei: update manpages
Catch up with recent developments.
2021-02-26lei q: -tt marks direct hits as "flagged"
This can be used to quickly distinguish messages which were direct hits when doing thread expansion vs messages that were merely part of the same thread. This is NOT mairix-derived behavior, but I occasionally found it useful when looking at results in an MUA to know whether a message was a direct hit or not. This makes "-t" consistent with non-"-t" cases as far as keyword reading goes.
2021-02-23doc: lei: favor "-o format:$PATHNAME" over "-f"
The --format argument is redundant and may be dropped entirely. Update the lei manpages to prefer the format prefix. cf. https://public-inbox.org/meta/20210217044032.GA17934@dcvr/
2021-02-11doc: lei: update manpages
Catch up with recent developments.
2021-02-11doc: lei q: use 'mfolder' as --output placeholder
'mfolder' is familiar to mairix users, and 'path' isn't a good choice because support will be added for IMAP. Link: https://public-inbox.org/meta/YCBh62OqkYnr5cqw@dcvr
2021-02-07lei: replace --thread with --threads
Nobody is expected to use long options, but for consistency with mairix(1), we'll use the pluralized option throughout (including existing PublicInbox::{Search,SearchView}). Link: https://public-inbox.org/meta/20210206090119.GA14519@dcvr/
2021-02-07lei: remove --mua-cmd alias for --mua
While "mua-cmd" may be more accurate, nobody is expected to type 4 extra characters. It's a needless ambiguity with no precedence or prior art to follow. Link: https://public-inbox.org/meta/20210206090119.GA14519@dcvr/
2021-02-03doc: lei-q: note "-a" and link to Xapian QueryParser
"-a" is supported by mairix, too. We should also note somewhere the query parsing features supported by Xapian.
2021-02-01doc: start manpages for lei commands
Add manpages for lei and the currently implemented subcommands. The included options and their descriptions follow to a large degree the --help output, dropping some options that are not currently wired up.