This series updates the lei manpages, continuing from <20210201055704.26683-1-kyle@kyleam.com>. It covers changes up to the current tip of master (e49cf9c629c..7a1fe192b9f). [1/4] doc: lei q: use 'mfolder' as --output placeholder [2/4] doc: lei: prefer 'location' and 'dirname' [3/4] doc: add lei-import(1) [4/4] doc: lei: update manpages Documentation/lei-add-external.pod | 66 +++++++++++++++++++++++++-- Documentation/lei-forget-external.pod | 2 +- Documentation/lei-import.pod | 54 ++++++++++++++++++++++ Documentation/lei-init.pod | 4 +- Documentation/lei-ls-external.pod | 17 ++++++- Documentation/lei-overview.pod | 17 ++++++- Documentation/lei-q.pod | 46 ++++++++++++++++++- Documentation/lei.pod | 4 +- Documentation/txt2pre | 1 + MANIFEST | 1 + Makefile.PL | 2 +- 11 files changed, 199 insertions(+), 15 deletions(-) create mode 100644 Documentation/lei-import.pod base-commit: 7a1fe192b9f63f057a21cb60c5e0e85b2ca34d50 -- 2.30.0
'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 --- Documentation/lei-q.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod index 8f053a55..405cf48f 100644 --- a/Documentation/lei-q.pod +++ b/Documentation/lei-q.pod @@ -16,7 +16,7 @@ TODO: Give common prefixes, or at least a description/reference. =over -=item -o PATH, --output=PATH, --mfolder=PATH +=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER Destination for results (e.g., C<path/to/Maildir> or - for stdout). -- 2.30.0
This follows the help output change in 52342875 (lei help: split out into separate file, 2021-02-06). --- Documentation/lei-add-external.pod | 4 ++-- Documentation/lei-forget-external.pod | 2 +- Documentation/lei-init.pod | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod index dd87be62..ebefb4cf 100644 --- a/Documentation/lei-add-external.pod +++ b/Documentation/lei-add-external.pod @@ -4,12 +4,12 @@ lei-add-external - add inbox or external index =head1 SYNOPSIS -lei add-external [OPTIONS] URL_OR_PATHNAME +lei add-external [OPTIONS] LOCATION =head1 DESCRIPTION Configure lei to search against an external (an inbox or external -index). When C<URL_OR_PATHNAME> is a local path, it should point to a +index). When C<LOCATION> is a local path, it should point to a directory that is a C<public.<name>.inboxdir> or C<extindex.<name>.topdir> value in ~/.public-inbox/config. diff --git a/Documentation/lei-forget-external.pod b/Documentation/lei-forget-external.pod index 40287bd3..3ad6bd45 100644 --- a/Documentation/lei-forget-external.pod +++ b/Documentation/lei-forget-external.pod @@ -4,7 +4,7 @@ lei-forget-external - forget external locations =head1 SYNOPSIS -lei forget-external [OPTIONS] URL_OR_PATHNAME [URL_OR_PATHNAME...] +lei forget-external [OPTIONS] LOCATION [LOCATION...] =head1 DESCRIPTION diff --git a/Documentation/lei-init.pod b/Documentation/lei-init.pod index 8a8022fb..bc687f72 100644 --- a/Documentation/lei-init.pod +++ b/Documentation/lei-init.pod @@ -4,11 +4,11 @@ lei-init - initialize storage =head1 SYNOPSIS -lei init [OPTIONS] [PATHNAME] +lei init [OPTIONS] [DIRNAME] =head1 DESCRIPTION -Initialize local writable storage for L<lei(1)>. If C<PATHNAME> is +Initialize local writable storage for L<lei(1)>. If C<DIRNAME> is unspecified, the storage is created at C<$XDG_DATA_HOME/lei/store>. C<leistore.dir> in C<$XDG_CONFIG_HOME/lei/config> records this location. -- 2.30.0
--- Documentation/lei-add-external.pod | 2 +- Documentation/lei-import.pod | 54 ++++++++++++++++++++++++++++++ Documentation/lei-overview.pod | 10 +++++- Documentation/lei.pod | 4 +-- Documentation/txt2pre | 1 + MANIFEST | 1 + Makefile.PL | 2 +- 7 files changed, 69 insertions(+), 5 deletions(-) create mode 100644 Documentation/lei-import.pod diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod index ebefb4cf..1be3f905 100644 --- a/Documentation/lei-add-external.pod +++ b/Documentation/lei-add-external.pod @@ -44,6 +44,6 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> =head1 SEE ALSO -L<lei-forget-external(1)>, L<lei-ls-external(1)>, +L<lei-forget-external(1)>, L<lei-ls-external(1)>, L<lei-import(1)>, L<public-inbox-index(1)>, L<public-inbox-extindex(1)>, L<public-inbox-extindex-format(5)> diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod new file mode 100644 index 00000000..14ca2d45 --- /dev/null +++ b/Documentation/lei-import.pod @@ -0,0 +1,54 @@ +=head1 NAME + +lei-import - one-time import of messages into local store + +=head1 SYNOPSIS + +lei import [OPTIONS] LOCATION [LOCATION...] + +lei import [OPTIONS] --stdin + +=head1 DESCRIPTION + +Import messages into the local storage of L<lei(1)>. C<LOCATION> is a +source of messages: a directory (Maildir) or a file (whose format is +specified via C<--format>). + +TODO: Update when URL support is added. + +=head1 OPTIONS + +=over + +=item -f MAIL_FORMAT, --format=MAIL_FORMAT + +Message input format: C<eml>, C<mboxrd>, C<mboxcl2>, C<mboxcl>, +C<mboxo>. + +=item --stdin + +Read messages from stdin. + +=item --no-kw, --no-keywords, --no-flags + +Don't import message keywords (or "flags" in IMAP terminology). + +=back + +=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/> + +=head1 COPYRIGHT + +Copyright 2021 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 + +L<lei-add-external(1)> diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod index d1903045..33ddb528 100644 --- a/Documentation/lei-overview.pod +++ b/Documentation/lei-overview.pod @@ -12,7 +12,15 @@ provides some basic examples. L<lei-init(1)> initializes writable local storage based on L<public-inbox-v2-format(5)>. -TODO: Extend when lei-import and friends are added. +=head2 EXAMPLES + +=over + +=item $ lei import --format=mboxrd t.mbox + +Import the messages from an mbox into the local storage. + +=back =head1 EXTERNALS diff --git a/Documentation/lei.pod b/Documentation/lei.pod index e12a157d..9ce9e9a4 100644 --- a/Documentation/lei.pod +++ b/Documentation/lei.pod @@ -27,9 +27,9 @@ Subcommands for initializing and managing local, writable storage: =item * L<lei-init(1)> -=back +=item * L<lei-import(1)> -TODO: Add commands like lei-import once they're implemented. +=back The following subcommands can be used to manage and inspect external locations: diff --git a/Documentation/txt2pre b/Documentation/txt2pre index 604490ef..8421cad7 100755 --- a/Documentation/txt2pre +++ b/Documentation/txt2pre @@ -16,6 +16,7 @@ for (qw[lei(1) lei-daemon-kill(1) lei-daemon-pid(1) lei-forget-external(1) + lei-import(1) lei-init(1) lei-ls-external(1) lei-overview(7) diff --git a/MANIFEST b/MANIFEST index 92226d5a..1794d930 100644 --- a/MANIFEST +++ b/MANIFEST @@ -26,6 +26,7 @@ Documentation/lei-config.pod Documentation/lei-daemon-kill.pod Documentation/lei-daemon-pid.pod Documentation/lei-forget-external.pod +Documentation/lei-import.pod Documentation/lei-init.pod Documentation/lei-ls-external.pod Documentation/lei-overview.pod diff --git a/Makefile.PL b/Makefile.PL index 6fb0d560..89f1774e 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -45,7 +45,7 @@ $v->{-m1} = [ map { } @EXE_FILES, qw( lei-add-external lei-config lei-daemon-kill lei-daemon-pid - lei-forget-external lei-init lei-ls-external lei-q)]; + lei-forget-external lei-import lei-init lei-ls-external lei-q)]; $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format public-inbox-v2-format public-inbox-extindex-format) ]; $v->{-m7} = [ qw(lei-overview public-inbox-overview public-inbox-tuning) ]; -- 2.30.0
Catch up with recent developments. --- Documentation/lei-add-external.pod | 62 +++++++++++++++++++++++++++++- Documentation/lei-ls-external.pod | 17 +++++++- Documentation/lei-overview.pod | 7 +++- Documentation/lei-q.pod | 44 +++++++++++++++++++++ 4 files changed, 125 insertions(+), 5 deletions(-) diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod index 1be3f905..3bc0ba83 100644 --- a/Documentation/lei-add-external.pod +++ b/Documentation/lei-add-external.pod @@ -9,12 +9,14 @@ lei add-external [OPTIONS] LOCATION =head1 DESCRIPTION Configure lei to search against an external (an inbox or external -index). When C<LOCATION> is a local path, it should point to a -directory that is a C<public.<name>.inboxdir> or +index). When C<LOCATION> is an existing local path, it should point +to a directory that is a C<public.<name>.inboxdir> or C<extindex.<name>.topdir> value in ~/.public-inbox/config. =head1 OPTIONS +TODO: mention curl options? + =over =item --boost=NUMBER @@ -23,6 +25,62 @@ Set priority of a new or existing location. Default: 0 +=item --mirror=URL + +Create C<LOCATION> by mirroring the public-inbox at C<URL>. + +=item -v, --verbose + +Provide more feedback on stderr. + +=item -q, --quiet + +Suppress feedback messages. + +=back + +=head2 MIRRORING + +=over + +=item --torsocks=auto|no|yes, --no-torsocks + +Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks. + +Default: C<auto> + +=item --inbox-version=NUM + +Force a public-inbox version (must be C<1> or C<2>). + +=back + +The following options are passed to L<public-inbox-init(1)>: + +=over + +=item -j JOBS, --jobs=JOBS + +=item -L LEVEL, --indexlevel=LEVEL + +=back + +The following options are passed to L<public-inbox-index(1)>: + +=over + +=item --batch-size=SIZE + +=item --compact + +=item -j JOBS, --jobs=JOBS + +=item --max-size=SIZE + +=item --sequential-shard + +=item --skip-docdata + =back =head1 FILES diff --git a/Documentation/lei-ls-external.pod b/Documentation/lei-ls-external.pod index 1735faa9..85d951f0 100644 --- a/Documentation/lei-ls-external.pod +++ b/Documentation/lei-ls-external.pod @@ -4,16 +4,29 @@ lei-ls-external - list inbox and external index locations =head1 SYNOPSIS -lei ls-external [OPTIONS] +lei ls-external [OPTIONS] [FILTER] =head1 DESCRIPTION -List configured externals. +List configured externals. If C<FILTER> is given, restrict the output +to matching entries. =head1 OPTIONS =over +=item -g, --globoff + +Do not match C<FILTER> using C<*?> wildcards and C<[]> ranges. + +=item --local + +Limit operations to the local filesystem. + +=item --remote + +Limit operations to those requiring network access. + =item -z, -0 Use C<\0> (NUL) instead of newline (CR) to delimit lines. diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod index 33ddb528..840d011b 100644 --- a/Documentation/lei-overview.pod +++ b/Documentation/lei-overview.pod @@ -27,7 +27,7 @@ Import the messages from an mbox into the local storage. In addition to the above store, lei can make read-only queries to "externals": inboxes and external indices. An external can be registered by passing a URL or local path to L<lei-add-external(1)>. -For local paths, the external needs to be indexed with +For existing local paths, the external needs to be indexed with L<public-inbox-index(1)> (in the case of a regular inbox) or L<public-inbox-extindex(1)> (in the case of an external index). @@ -39,6 +39,11 @@ L<public-inbox-extindex(1)> (in the case of an external index). Add a remote external for public-inbox's inbox. +=item $ lei add-external --mirror https://public-inbox.org/meta/ path + +Clone L<https://public-inbox.org/meta/> to C<path>, index it with +L<public-inbox-index(1)>, and add it as a local external. + =back =head1 SEARCHING diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod index 405cf48f..c8df6fc7 100644 --- a/Documentation/lei-q.pod +++ b/Documentation/lei-q.pod @@ -6,6 +6,8 @@ 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. @@ -14,8 +16,14 @@ TODO: Give common prefixes, or at least a description/reference. =head1 OPTIONS +TODO: mention curl options? + =over +=item --stdin + +Read search terms from stdin. + =item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER Destination for results (e.g., C<path/to/Maildir> or - for stdout). @@ -43,6 +51,18 @@ For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>, or C<neomutt>. +=item --alert=COMMAND[,COMMAND...] + +Run C<COMMAND> after writing to output. C<:WINCH> indicates to send +C<SIGWINCH> 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 -a, --augment Augment output destination instead of clobbering it. @@ -74,6 +94,26 @@ Limit operations to those requiring network access. Don't include results from externals. +=item -I LOCATION, --include=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 -g, --globoff + +Do not match locations using C<*?> wildcards and C<[]> ranges. This +option applies to C<--include>, C<--exclude>, and C<--only>. + =item -NUMBER, -n NUMBER, --limit=NUMBER Limit the number of matches. @@ -101,6 +141,10 @@ Default: C<received> Provide more feedback on stderr. +=item -q, --quiet + +Suppress feedback messages. + =item --torsocks=auto|no|yes, --no-torsocks Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks. -- 2.30.0
Thanks, pushed as f310a5054fb8e215885f0b48afac44ff32ca1d56 to https://80x24.org/public-inbox.git