[PATCH 0/4] doc: lei: some manpage updaets

[PATCH 0/4] doc: lei: some manpage updaets

[Eric Wong]

Tring ot ut somthing mildly coharent.  Insomnia :<

Eric Wong (4):
  doc: lei blob+rediff+p2q: add notes about git directory
  doc: lei-overview: implicit stdin, correct Inline::C notes
  doc: lei-index: remove --stdin, reword -F
  doc: lei: manpages for export-kw and refresh-mail-sync

 Documentation/lei-blob.pod              |  6 ++-
 Documentation/lei-export-kw.pod         | 52 ++++++++++++++++++++++
 Documentation/lei-index.pod             | 18 +++-----
 Documentation/lei-overview.pod          | 22 +++++-----
 Documentation/lei-p2q.pod               |  2 +-
 Documentation/lei-rediff.pod            | 23 +++++++++-
 Documentation/lei-refresh-mail-sync.pod | 57 +++++++++++++++++++++++++
 MANIFEST                                |  2 +
 Makefile.PL                             |  5 ++-
 9 files changed, 158 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/lei-export-kw.pod
 create mode 100644 Documentation/lei-refresh-mail-sync.pod

[PATCH 1/4] doc: lei blob+rediff+p2q: add notes about git directory

[Eric Wong]

Try to clarify these commands are intended to be useful for
git-using (usually software) projects (and not the bare git
repos we use internally).

We'll also document some commonly useful git-diff switches
in the lei-rediff man page to highlight the usefulness
of the command.
---
 Documentation/lei-blob.pod   |  6 ++++--
 Documentation/lei-p2q.pod    |  2 +-
 Documentation/lei-rediff.pod | 23 +++++++++++++++++++++--
 3 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 5b611d11ba1f..429d206e358e 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -10,8 +10,8 @@ lei blob [OPTIONS] OID
 
 Display a git blob.  The blob may correspond to a message from the
 local store, an existing blob in the current repository, or a
-not-yet-created blob in the current repository that can be
-reconstructed from a message.
+not-yet-created blob in the current git project repository (if any)
+that can be reconstructed from a message.
 
 =head1 OPTIONS
 
@@ -22,6 +22,8 @@ reconstructed from a message.
 Specify an additional .git/ directory to scan.  This option may be
 given multiple times.
 
+Default: the output of C<git rev-parse --git-dir>
+
 =item --no-cwd
 
 Do not look in the git repository of the current working directory.
diff --git a/Documentation/lei-p2q.pod b/Documentation/lei-p2q.pod
index 44798ac3d2a0..1068ff0beb27 100644
--- a/Documentation/lei-p2q.pod
+++ b/Documentation/lei-p2q.pod
@@ -16,7 +16,7 @@ inbox.
 
 The patch can be provided on stdin or as a file.  Alternatively, when
 an argument is given that does not point to an existing file, it is
-taken as a reference to a commit in the current repository, and
+taken as a reference to a commit in the current git repository, and
 L<git-format-patch(1)> is used to generate the patch.
 
 =head1 OPTIONS
diff --git a/Documentation/lei-rediff.pod b/Documentation/lei-rediff.pod
index c7db6c1e20b6..f34e946ffe52 100644
--- a/Documentation/lei-rediff.pod
+++ b/Documentation/lei-rediff.pod
@@ -15,10 +15,15 @@ the specified L<git-diff(1)> options.  This is useful if you want to
 change the display of the original patch (e.g., increasing context,
 coloring moved lines differently, or using an external diff viewer).
 
+It relies on the contents of the .git directory of your current
+project working tree.  In other words, it works anywhere
+L<git-am(1)> works.  Otherwise, C<--git-dir=> may be specified
+any number of times to add repositories to build blob data from.
+
 =head1 OPTIONS
 
-In addition to many L<git-diff(1)>, the following options are
-supported.
+In addition to many L<git-diff(1)> options (e.g. C<-W>, C<-w>,
+C<-U $LINES>) the following options are supported:
 
 =over
 
@@ -27,15 +32,29 @@ supported.
 Read message from stdin.  This is implicit if no arguments are given
 and stdin is a pipe or regular file.
 
+For users of text editors and pagers capable of piping its
+buffer to arbitrary commands, it is useful to pipe a patch email
+to C<lei rediff> before piping it to L<git-am(1)>.  The output
+of C<lei rediff> is compatible with C<git am> if its input was a
+patch email.
+
 =item --git-dir=DIR
 
 Specify an additional .git/ directory to scan.  This option may be
 given multiple times.
 
+Default: the output of C<git rev-parse --git-dir>
+
 =item --no-cwd
 
 Do not look in the git repository of the current working directory.
 
+=item -q
+
+=item --quiet
+
+Suppress progress output.
+
 =item -v
 
 =item --verbose

[PATCH 2/4] doc: lei-overview: implicit stdin, correct Inline::C notes

[Eric Wong]

Implicit stdin based on standard input being a pipe or regular
file is here to stay, so save users the trouble of typing '-'
or '--stdin'.

Inline::C is required as of commit 1d6e1f9a6a66 (lei: require
Socket::MsgHdr or Inline::C, drop oneshot, 2021-05-26); but
Socket::MsgHdr still gives a noticeable improvement in bash
completion speed.

Also, spell-out "MESSAGE-ID" since "MID" is actually not a
common abbreviation ("MSGID" is used by RFC 3977 and several
other RFCs, I recall).
---
 Documentation/lei-overview.pod | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index e80cb094cecc..40a7b0aadd04 100644
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -33,7 +33,7 @@ Show message with the git blob OID of 59ec517f9.  If a message with
 that OID isn't found, check if the current git repository has the
 blob, trying to reconstruct it from a message if needed.
 
-=item $ lei blob 59ec517f9 | lei tag - -F eml +kw:flagged +L:next
+=item $ lei blob 59ec517f9 | lei tag -F eml +kw:flagged +L:next
 
 Set the "flagged" keyword and "next" label on the message with the
 blob OID of 59ec517f9.
@@ -92,18 +92,18 @@ and written.
 
 Search for all flagged messages that also have a "next" label.
 
-=item $ lei p2q HEAD | lei q --stdin -tt -o /tmp/mdir
+=item $ lei p2q HEAD | lei q -tt -o /tmp/mdir
 
 Search for messages that have post-image git blob IDs that match those
 of the current repository's HEAD commit, writing them to the Maildir
 directory "mdir" and flagging the messages that were an exact match.
 
-=item $ git show -s HEAD | lei lcat -
+=item $ git show -s HEAD | lei lcat
 
 Display a local message for the public-inbox link contained in a
 commit message.
 
-=item $ lei q -f text m:MID | lei rediff -U5 -
+=item $ lei q -f text m:MESSAGE-ID | lei rediff -U5
 
 Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
 diff with five context lines.  Unless C<--git-dir> is specified, this
@@ -114,13 +114,15 @@ code repository.
 
 =head1 PERFORMANCE NOTES
 
-L<Inline::C> is recommended for performance.  To enable it, create
-C<~/.cache/public-inbox/inline-c/>.
+L<Inline::C> is required, lei runs as a background daemon to reduce
+startup costs and can provide real-time L<kqueue(2)>/L<inotify(7)>
+Maildir monitoring.  L<IO::KQueue> (p5-IO-KQueue on FreeBSD) and
+L<Linux::Inotify2> (liblinux-inotify2-perl and perl-Linux-Inotify2 in
+.deb and .rpm-based distros, respectively) are recommended.
 
-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).
+L<Socket::MsgHdr> is optional (libsocket-msghdr-perl in Debian),
+and further improves startup performance.  Its effect is most felt
+when using shell completion.
 
 =head1 BASH COMPLETION
 

[PATCH 3/4] doc: lei-index: remove --stdin, reword -F

[Eric Wong]

lei-index really only works for Maildir, at the moment.
---
 Documentation/lei-index.pod | 18 +++++-------------
 1 file changed, 5 insertions(+), 13 deletions(-)

diff --git a/Documentation/lei-index.pod b/Documentation/lei-index.pod
index bd125bcceb63..9e72026351a1 100644
--- a/Documentation/lei-index.pod
+++ b/Documentation/lei-index.pod
@@ -6,8 +6,6 @@ lei-index - index messages without importing them into lei/store
 
 lei index [OPTIONS] FOLDER
 
-lei index [OPTIONS] --stdin
-
 =head1 DESCRIPTION
 
 Similar to L<lei-import(1)>, but does not store a copy of
@@ -26,22 +24,16 @@ messages into C<lei/store>.
 
 =over
 
-=item -
-
-=item --stdin
-
-Read input from standard input.  This is the default if standard
-input is a pipe or regular file and there are no arguments on
-the command-line.
-
 =item -F MAIL_FORMAT
 
 =item --in-format=MAIL_FORMAT
 
-Message input format: C<eml>, C<maildir>, C<imap>, C<imaps>, C<nntp>,
-C<nntps>, C<mboxrd>, C<mboxcl2>, C<mboxcl>, or C<mboxo>.
+There is currently no need for this option.  It will support C<mh>,
+eventually.  For now, the default (and only supported) format is
+C<maildir>.  When IMAP and NNTP support are fleshed out, those
+formats will be inferred from their URLs.
 
-Default: C<eml> when reading from stdin
+Default: C<maildir>
 
 =item -q
 

[PATCH 4/4] doc: lei: manpages for export-kw and refresh-mail-sync

[Eric Wong]

Something is better than nothing.
---
 Documentation/lei-export-kw.pod         | 52 ++++++++++++++++++++++
 Documentation/lei-refresh-mail-sync.pod | 57 +++++++++++++++++++++++++
 MANIFEST                                |  2 +
 Makefile.PL                             |  5 ++-
 4 files changed, 115 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/lei-export-kw.pod
 create mode 100644 Documentation/lei-refresh-mail-sync.pod

diff --git a/Documentation/lei-export-kw.pod b/Documentation/lei-export-kw.pod
new file mode 100644
index 000000000000..cf482ca0d307
--- /dev/null
+++ b/Documentation/lei-export-kw.pod
@@ -0,0 +1,52 @@
+=head1 NAME
+
+lei-export-kw - export keywords (flags) to Maildir and IMAP folders
+
+=head1 SYNOPSIS
+
+lei export-kw --all=[<remote|local>]
+
+lei export-kw MFOLDER [MFOLDER...]
+
+=head1 DESCRIPTION
+
+C<lei export-kw> propagates keywords (e.g. C<seen>, C<answered>,
+C<flagged>, etc.) from lei/store to IMAP folders and/or Maildirs.
+
+It does not delete, write, nor modify messages themselves;
+it only sets metadata on Maildirs and IMAP folders.
+
+=head1 OPTIONS
+
+=over
+
+=item --all
+
+Export to all local Maildirs and remote IMAP folders
+
+=item --all=local
+
+Export all local Maildirs
+
+=item --all=remote
+
+Export all remote IMAP folders
+
+=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://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
+
+=head1 COPYRIGHT
+
+Copyright 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-refresh-mail-sync(1)>, L<lei-tag(1)>
diff --git a/Documentation/lei-refresh-mail-sync.pod b/Documentation/lei-refresh-mail-sync.pod
new file mode 100644
index 000000000000..aefd516fad93
--- /dev/null
+++ b/Documentation/lei-refresh-mail-sync.pod
@@ -0,0 +1,57 @@
+=head1 NAME
+
+lei-refresh-mail-sync - refresh sync info with Maildir, IMAP
+
+=head1 SYNOPSIS
+
+lei refresh-mail-sync --all[=<remote|local>]
+
+lei refresh-mail-sync MFOLDER [MFOLDER...]
+
+=head1 DESCRIPTION
+
+C<lei refresh-mail-sync> is intended to to keep old messages
+indexed with L<lei-index(1)> retrievable if Maildir flags change
+a filename.  It will prune invalid entries for messages which no
+longer exist in a Maildir.
+
+It is also useful for ensuring L<lei-export-kw(1)> can propagate
+keyword (flag) changes to Maildirs and IMAP folders.
+
+It only needs read-only access to Maildirs and IMAP folders
+and will not attempt to write to them at all.
+
+=head1 OPTIONS
+
+=over
+
+=item --all
+
+Refresh all local Maildirs and remote IMAP folders
+
+=item --all=local
+
+Refresh all local Maildirs
+
+=item --all=remote
+
+Refresh all remote IMAP folders
+
+=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://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
+
+=head1 COPYRIGHT
+
+Copyright 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-index(1)>, L<lei-export-kw(1)>
diff --git a/MANIFEST b/MANIFEST
index 8c2e964b3dce..3595195a6996 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -28,6 +28,7 @@ Documentation/lei-convert.pod
 Documentation/lei-daemon-kill.pod
 Documentation/lei-daemon-pid.pod
 Documentation/lei-edit-search.pod
+Documentation/lei-export-kw.pod
 Documentation/lei-forget-external.pod
 Documentation/lei-forget-search.pod
 Documentation/lei-import.pod
@@ -43,6 +44,7 @@ Documentation/lei-overview.pod
 Documentation/lei-p2q.pod
 Documentation/lei-q.pod
 Documentation/lei-rediff.pod
+Documentation/lei-refresh-mail-sync.pod
 Documentation/lei-rm.pod
 Documentation/lei-security.pod
 Documentation/lei-store-format.pod
diff --git a/Makefile.PL b/Makefile.PL
index f56445ae422d..00a558d12472 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -46,9 +46,12 @@ $v->{-m1} = [ map {
 	} @EXE_FILES,
 	qw(
 	lei-add-external lei-blob lei-config lei-convert lei-edit-search
+	lei-export-kw
 	lei-daemon-kill lei-daemon-pid lei-forget-external lei-forget-search
 	lei-import lei-index lei-init lei-lcat lei-ls-external lei-ls-label
-	lei-ls-mail-sync lei-ls-search lei-p2q lei-q lei-rediff lei-rm lei-tag
+	lei-ls-mail-sync lei-ls-search lei-p2q lei-q lei-rediff
+	lei-refresh-mail-sync
+	lei-rm lei-tag
 	lei-up)];
 $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
 		public-inbox-v2-format public-inbox-extindex-format