user/dev discussion of public-inbox itself
 help / color / mirror / code / Atom feed
* [PATCH 0/3] doc: lei manpages, round 3
@ 2021-02-27 18:03 Kyle Meyer
  2021-02-27 18:03 ` [PATCH 1/3] doc: lei: update manpages Kyle Meyer
                   ` (3 more replies)
  0 siblings, 4 replies; 5+ messages in thread
From: Kyle Meyer @ 2021-02-27 18:03 UTC (permalink / raw)
  To: meta

This series updates the lei manpages, continuing from
<20210211040415.28557-1-kyle@kyleam.com>.  It covers changes up to the
current tip of master (f310a5054fb8e215..903eac79aa86d17c).

I didn't add a manpage for lei-convert, as I wasn't sure if that
should be considered mostly an internal tool for testing purposes.
Thoughts?

  [1/3] doc: lei: update manpages
  [2/3] doc: lei-import: drop markup of "stdin"
  [3/3] doc: lei-overview: add performance and bash completion sections

 Documentation/lei-import.pod   | 21 +++++++++++++++------
 Documentation/lei-overview.pod | 17 +++++++++++++++++
 Documentation/lei-q.pod        | 32 ++++++++++++++++++++++++--------
 Documentation/lei.pod          | 15 ++++++++++++++-
 Documentation/txt2pre          |  1 +
 5 files changed, 71 insertions(+), 15 deletions(-)


base-commit: 903eac79aa86d17c0b8f888d160d44977899515b
-- 
2.30.1


^ permalink raw reply	[flat|nested] 5+ messages in thread

* [PATCH 1/3] doc: lei: update manpages
  2021-02-27 18:03 [PATCH 0/3] doc: lei manpages, round 3 Kyle Meyer
@ 2021-02-27 18:03 ` Kyle Meyer
  2021-02-27 18:03 ` [PATCH 2/3] doc: lei-import: drop markup of "stdin" Kyle Meyer
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 5+ messages in thread
From: Kyle Meyer @ 2021-02-27 18:03 UTC (permalink / raw)
  To: meta

Catch up with recent developments.
---
 Documentation/lei-import.pod | 19 ++++++++++++++-----
 Documentation/lei-q.pod      | 32 ++++++++++++++++++++++++--------
 Documentation/lei.pod        | 15 ++++++++++++++-
 Documentation/txt2pre        |  1 +
 4 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index ef20e2f6305cf6ff..7d5b2576808fdb61 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -11,12 +11,14 @@ 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.  For a regular
-file, the location must have a C<E<lt>formatE<gt>:> prefix specifying
-one of the following formats: C<eml>, C<mboxrd>, C<mboxcl2>,
-C<mboxcl>, or C<mboxo>.
+source of messages: a directory (Maildir), a file, or a URL
+(C<imap://>, C<imaps://>, C<nntp://>, or C<nntps://>).  URLs requiring
+authentication must use L<netrc(5)> and/or L<git-credential(1)> to
+fill in the username and password.
 
-TODO: Update when URL support is added.
+For a regular file, the location must have a C<E<lt>formatE<gt>:>
+prefix specifying one of the following formats: C<eml>, C<mboxrd>,
+C<mboxcl2>, C<mboxcl>, or C<mboxo>.
 
 =head1 OPTIONS
 
@@ -31,6 +33,13 @@ format prefix with C<LOCATION> is preferred.
 
 Read messages from stdin.
 
+=item --lock
+
+L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
+C<none>.
+
+Default: fcntl,dotlock
+
 =item --no-kw, --no-keywords, --no-flags
 
 Don't import message keywords (or "flags" in IMAP terminology).
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 0959beac38504841..e878157d93e2f7c5 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -26,18 +26,22 @@ Read search terms from stdin.
 
 =item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
 
-Destination for results (e.g., C<path/to/Maildir> or
-C<mboxcl2:path/to/mbox>).  The format can be specified by adding a
-C<E<lt>formatE<gt>:> prefix with any of these values: C<maildir>,
+Destination for results (e.g., C<path/to/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
+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>.
+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.
 
 TODO: Provide description of formats?
 
-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.
-
 Default: -
 
 =item -f FORMAT, --format=FORMAT
@@ -130,6 +134,18 @@ multiple times, in which case the search uses only the specified set.
 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<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
+C<none>.
+
+Default: fcntl,dotlock
+
 =item -NUMBER, -n NUMBER, --limit=NUMBER
 
 Limit the number of matches.
diff --git a/Documentation/lei.pod b/Documentation/lei.pod
index 9ce9e9a4dc6cde81..e1502122571ad521 100644
--- a/Documentation/lei.pod
+++ b/Documentation/lei.pod
@@ -4,7 +4,7 @@ lei - local email interface for public-inbox
 
 =head1 SYNOPSIS
 
-lei COMMAND
+lei [OPTIONS] COMMAND
 
 =head1 DESCRIPTION
 
@@ -19,6 +19,19 @@ indices).
 
 Available in public-inbox 1.7.0+.
 
+=head1 OPTIONS
+
+=over
+
+=item -C DIR
+
+Change current working directory to the specified directory before
+running the command.  This option can be given before or after
+C<COMMAND> and is accepted by all lei subcommands except
+L<lei-daemon-kill(1)>.
+
+=back
+
 =head1 COMMANDS
 
 Subcommands for initializing and managing local, writable storage:
diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 8421cad74e7b4321..3277531f9122b8d6 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -102,6 +102,7 @@ $xurls{'git-filter-repo(1)'} = 'https://github.com/newren/git-filter-repo'.
 $xurls{'ssoma(1)'} = 'https://ssoma.public-inbox.org/ssoma.txt';
 $xurls{'cgitrc(5)'} = 'https://git.zx2c4.com/cgit/tree/cgitrc.5.txt';
 $xurls{'prove(1)'} = 'https://perldoc.perl.org/prove.html';
+$xurls{'mbox(5)'} = 'https://manpages.debian.org/stable/mutt/mbox.5.en.html';
 
 my $str = do { local $/; <STDIN> };
 my ($title) = ($str =~ /\A([^\n]+)/);
-- 
2.30.1


^ permalink raw reply	[flat|nested] 5+ messages in thread

* [PATCH 2/3] doc: lei-import: drop markup of "stdin"
  2021-02-27 18:03 [PATCH 0/3] doc: lei manpages, round 3 Kyle Meyer
  2021-02-27 18:03 ` [PATCH 1/3] doc: lei: update manpages Kyle Meyer
@ 2021-02-27 18:03 ` Kyle Meyer
  2021-02-27 18:03 ` [PATCH 3/3] doc: lei-overview: add performance and bash completion sections Kyle Meyer
  2021-02-27 20:20 ` [PATCH 0/3] doc: lei manpages, round 3 Eric Wong
  3 siblings, 0 replies; 5+ messages in thread
From: Kyle Meyer @ 2021-02-27 18:03 UTC (permalink / raw)
  To: meta

stdin isn't placed in C<> elsewhere.
---
 Documentation/lei-import.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 7d5b2576808fdb61..7f4e37452dcb0671 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -26,7 +26,7 @@ C<mboxcl2>, C<mboxcl>, or C<mboxo>.
 
 =item -F MAIL_FORMAT, --in-format=MAIL_FORMAT
 
-Message input format.  Unless messages are given on C<stdin>, using a
+Message input format.  Unless messages are given on stdin, using a
 format prefix with C<LOCATION> is preferred.
 
 =item --stdin
-- 
2.30.1


^ permalink raw reply	[flat|nested] 5+ messages in thread

* [PATCH 3/3] doc: lei-overview: add performance and bash completion sections
  2021-02-27 18:03 [PATCH 0/3] doc: lei manpages, round 3 Kyle Meyer
  2021-02-27 18:03 ` [PATCH 1/3] doc: lei: update manpages Kyle Meyer
  2021-02-27 18:03 ` [PATCH 2/3] doc: lei-import: drop markup of "stdin" Kyle Meyer
@ 2021-02-27 18:03 ` Kyle Meyer
  2021-02-27 20:20 ` [PATCH 0/3] doc: lei manpages, round 3 Eric Wong
  3 siblings, 0 replies; 5+ messages in thread
From: Kyle Meyer @ 2021-02-27 18:03 UTC (permalink / raw)
  To: meta

Take care of a couple of the items mentioned at
<https://public-inbox.org/meta/20210218202818.GA19443@dcvr>.
---
 Documentation/lei-overview.pod | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index 62b62280ad2ddd69..c3379caa1bd15d69 100644
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -71,6 +71,23 @@ file by invoking C<mutt -f %f>.
 
 =back
 
+=head1 PERFORMANCE NOTES
+
+L<Inline::C> is recommended for performance.  To enable it, create
+C<~/.cache/public-inbox/inline-c/>.
+
+If Socket::MsgHdr is installed (libsocket-msghdr-perl in Debian), the
+first invocation of lei starts a daemon, reducing the startup cost of
+for future invocations (which is particularly important for Bash
+completion).
+
+=head1 BASH COMPLETION
+
+Preliminary Bash completion for lei is provided in
+C<contrib/completion/>.  Contributions adding support for other
+shells, as well as improvements to the existing Bash completion, are
+welcome.
+
 =head1 CONTACT
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
-- 
2.30.1


^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH 0/3] doc: lei manpages, round 3
  2021-02-27 18:03 [PATCH 0/3] doc: lei manpages, round 3 Kyle Meyer
                   ` (2 preceding siblings ...)
  2021-02-27 18:03 ` [PATCH 3/3] doc: lei-overview: add performance and bash completion sections Kyle Meyer
@ 2021-02-27 20:20 ` Eric Wong
  3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2021-02-27 20:20 UTC (permalink / raw)
  To: Kyle Meyer; +Cc: meta

Thanks, pushed as commit b4603182d50456dc410093efd4d921078559fd42

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2021-02-27 20:20 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-27 18:03 [PATCH 0/3] doc: lei manpages, round 3 Kyle Meyer
2021-02-27 18:03 ` [PATCH 1/3] doc: lei: update manpages Kyle Meyer
2021-02-27 18:03 ` [PATCH 2/3] doc: lei-import: drop markup of "stdin" Kyle Meyer
2021-02-27 18:03 ` [PATCH 3/3] doc: lei-overview: add performance and bash completion sections Kyle Meyer
2021-02-27 20:20 ` [PATCH 0/3] doc: lei manpages, round 3 Eric Wong

user/dev discussion of public-inbox itself

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/meta
	git clone --mirror http://czquwvybam4bgbro.onion/meta
	git clone --mirror http://hjrcffqmbrq6wope.onion/meta
	git clone --mirror http://ou63pmih66umazou.onion/meta

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 meta meta/ https://public-inbox.org/meta \
		meta@public-inbox.org
	public-inbox-index meta

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.mail.public-inbox.meta
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.mail.public-inbox.meta
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.mail.public-inbox.meta
	nntp://news.gmane.io/gmane.mail.public-inbox.general
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/public-inbox.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git