[PATCH 0/3] doc: lei manpages, round 3

[PATCH 0/3] doc: lei manpages, round 3

[Kyle Meyer]

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

[PATCH 1/3] doc: lei: update manpages

[Kyle Meyer]

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

[PATCH 2/3] doc: lei-import: drop markup of "stdin"

[Kyle Meyer]

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

[PATCH 3/3] doc: lei-overview: add performance and bash completion sections

[Kyle Meyer]

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

Re: [PATCH 0/3] doc: lei manpages, round 3

[Eric Wong]

Thanks, pushed as commit b4603182d50456dc410093efd4d921078559fd42