[PATCH 0/9] doc: lei manpages, round 5

[PATCH 0/9] doc: lei manpages, round 5

[Kyle Meyer]

This series updates the lei manpages, continuing from
<20210329031117.28516-1-kyle@kyleam.com>.  It covers changes up to the
current tip of master (236831da32b1240d..8cc23ac6f7a38479).

The second patch touches outside of lei manpages as a followup to
e226f18934eb7291 (doc: lei q: split =item aliases onto separate lines,
2021-04-28).

  [1/9] doc lei blob: avoid combined description of separate options
  [2/9] doc: split option variants into separate items
  [3/9] doc lei blob: point to lei-q for shared options
  [4/9] doc lei: resort lei-tag entries
  [5/9] doc lei q: fix a typo
  [6/9] doc lei q: add missing value for --lock
  [7/9] doc lei: add manpage for convert
  [8/9] doc lei: add manpages for new commands
  [9/9] doc lei: update manpages with new options

 Documentation/lei-add-external.pod            | 12 ++-
 Documentation/lei-blob.pod                    | 62 +++++++--------
 .../{lei-import.pod => lei-convert.pod}       | 40 ++++++----
 Documentation/lei-edit-search.pod             | 28 +++++++
 Documentation/lei-forget-external.pod         |  4 +-
 Documentation/lei-forget-search.pod           | 28 +++++++
 Documentation/lei-import.pod                  | 20 ++++-
 Documentation/lei-init.pod                    |  4 +-
 Documentation/lei-lcat.pod                    | 79 +++++++++++++++++++
 Documentation/lei-ls-external.pod             |  8 +-
 Documentation/lei-ls-label.pod                |  8 +-
 ...i-ls-external.pod => lei-ls-mail-sync.pod} | 22 +++---
 Documentation/lei-ls-search.pod               | 65 +++++++++++++++
 Documentation/lei-overview.pod                | 12 +++
 Documentation/lei-p2q.pod                     |  8 +-
 Documentation/lei-q.pod                       | 16 +++-
 Documentation/lei-rediff.pod                  | 79 +++++++++++++++++++
 Documentation/lei-tag.pod                     |  8 +-
 Documentation/lei-up.pod                      | 48 +++++++++++
 Documentation/lei.pod                         | 18 +++++
 Documentation/public-inbox-compact.pod        |  6 +-
 Documentation/public-inbox-convert.pod        |  4 +-
 Documentation/public-inbox-daemon.pod         | 16 +++-
 Documentation/public-inbox-extindex.pod       |  4 +-
 Documentation/public-inbox-imapd.pod          |  4 +-
 Documentation/public-inbox-index.pod          | 12 ++-
 Documentation/public-inbox-init.pod           | 20 +++--
 Documentation/public-inbox-nntpd.pod          |  4 +-
 Documentation/public-inbox-xcpdb.pod          | 14 +++-
 Documentation/txt2pre                         | 11 ++-
 MANIFEST                                      |  8 ++
 Makefile.PL                                   |  8 +-
 32 files changed, 580 insertions(+), 100 deletions(-)
 copy Documentation/{lei-import.pod => lei-convert.pod} (54%)
 create mode 100644 Documentation/lei-edit-search.pod
 create mode 100644 Documentation/lei-forget-search.pod
 create mode 100644 Documentation/lei-lcat.pod
 copy Documentation/{lei-ls-external.pod => lei-ls-mail-sync.pod} (64%)
 create mode 100644 Documentation/lei-ls-search.pod
 create mode 100644 Documentation/lei-rediff.pod
 create mode 100644 Documentation/lei-up.pod


base-commit: 8cc23ac6f7a3847977ec57c2a3e9e391fdb94da6
-- 
2.31.1

[PATCH 1/9] doc lei blob: avoid combined description of separate options

[Kyle Meyer]

The next commit will update the manpages to split each option's
variants into separate items.  This change won't mix well with
--oid-a, --path-a, and --path-b.  These different options all share a
single description, and, if each form is on its own line, the link
between the variants of each option would no longer be clear.

Use a dedicated description for each option to avoid confusion.
---
 Documentation/lei-blob.pod | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index bb316e71..341b5505 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -33,12 +33,15 @@ C<--oid-a>, C<--path-a>, and C<--path-b>.
 
 =item -A OID-A, --oid-a=OID-A
 
+Provide pre-image object ID as a hint for reconstructing C<OID>.
+
 =item -a PATH-A, --path-a=PATH-A
 
+Provide pre-image pathname as a hint for reconstructing C<OID>.
+
 =item -b PATH-B, --path-b=PATH-B
 
-Provide pre-image object ID, pre-image pathname, or post-image
-pathname as a hint for reconstructing C<OID>.
+Provide post-image pathname as a hint for reconstructing C<OID>.
 
 =for comment
 TODO: The below options are shared with lei-q.  Any good approaches to
-- 
2.31.1

[PATCH 2/9] doc: split option variants into separate items

[Kyle Meyer]

e226f18934eb7291 modified the lei-q manpage so that each variant of an
option gets a dedicated =item to make L</--xyz> look nicer and to
follow the Perl core documentation.  Do the same for the other
manpages.

Note that this still leaves the variants of an option grouped in one
scenario: when a list of options without descriptions is presented as
a pointer to another location.  Splitting the variants in that case
would make it harder for the reader to tell what the distinct options
are.
---
 Documentation/lei-add-external.pod      | 12 +++++++++---
 Documentation/lei-blob.pod              | 24 ++++++++++++++++++------
 Documentation/lei-forget-external.pod   |  4 +++-
 Documentation/lei-import.pod            |  4 +++-
 Documentation/lei-init.pod              |  4 +++-
 Documentation/lei-ls-external.pod       |  8 ++++++--
 Documentation/lei-ls-label.pod          |  8 ++++++--
 Documentation/lei-p2q.pod               |  8 ++++++--
 Documentation/lei-tag.pod               |  8 ++++++--
 Documentation/public-inbox-compact.pod  |  6 +++++-
 Documentation/public-inbox-convert.pod  |  4 +++-
 Documentation/public-inbox-daemon.pod   | 16 ++++++++++++----
 Documentation/public-inbox-extindex.pod |  4 +++-
 Documentation/public-inbox-imapd.pod    |  4 +++-
 Documentation/public-inbox-index.pod    | 12 +++++++++---
 Documentation/public-inbox-init.pod     | 20 +++++++++++++++-----
 Documentation/public-inbox-nntpd.pod    |  4 +++-
 Documentation/public-inbox-xcpdb.pod    | 14 +++++++++++---
 18 files changed, 124 insertions(+), 40 deletions(-)

diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod
index ad0e1d07..71229865 100644
--- a/Documentation/lei-add-external.pod
+++ b/Documentation/lei-add-external.pod
@@ -30,11 +30,15 @@ Default: 0
 
 Create C<LOCATION> by mirroring the public-inbox at C<URL>.
 
-=item -v, --verbose
+=item -v
+
+=item --verbose
 
 Provide more feedback on stderr.
 
-=item -q, --quiet
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
@@ -44,7 +48,9 @@ Suppress feedback messages.
 
 =over
 
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 341b5505..76918324 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -31,15 +31,21 @@ Do not look in the git repository of the current working directory.
 Do not look in mail storage for C<OID>.  This is implied by
 C<--oid-a>, C<--path-a>, and C<--path-b>.
 
-=item -A OID-A, --oid-a=OID-A
+=item -A OID-A
+
+=item --oid-a=OID-A
 
 Provide pre-image object ID as a hint for reconstructing C<OID>.
 
-=item -a PATH-A, --path-a=PATH-A
+=item -a PATH-A
+
+=item --path-a=PATH-A
 
 Provide pre-image pathname as a hint for reconstructing C<OID>.
 
-=item -b PATH-B, --path-b=PATH-B
+=item -b PATH-B
+
+=item --path-b=PATH-B
 
 Provide post-image pathname as a hint for reconstructing C<OID>.
 
@@ -61,7 +67,9 @@ Limit operations to those requiring network access.
 
 Don't include results from externals.
 
-=item -I LOCATION, --include=LOCATION
+=item -I LOCATION
+
+=item --include=LOCATION
 
 Include specified external in search.  This option may be given
 multiple times.
@@ -81,11 +89,15 @@ multiple times, in which case the search uses only the specified set.
 Disable the default behavior of memoizing remote messages into the
 local store.
 
-=item -v, --verbose
+=item -v
+
+=item --verbose
 
 Provide more feedback on stderr.
 
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
diff --git a/Documentation/lei-forget-external.pod b/Documentation/lei-forget-external.pod
index 0d065a76..e0e3b8e1 100644
--- a/Documentation/lei-forget-external.pod
+++ b/Documentation/lei-forget-external.pod
@@ -16,7 +16,9 @@ future search results.
 
 =over
 
-=item -q, --quiet
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 5b6a6f26..1fe2dac3 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -24,7 +24,9 @@ C<mboxcl2>, C<mboxcl>, or C<mboxo>.
 
 =over
 
-=item -F MAIL_FORMAT, --in-format=MAIL_FORMAT
+=item -F MAIL_FORMAT
+
+=item --in-format=MAIL_FORMAT
 
 Message input format.  Unless messages are given on stdin, using a
 format prefix with C<LOCATION> is preferred.
diff --git a/Documentation/lei-init.pod b/Documentation/lei-init.pod
index 54ae9dbe..4bfc3b9f 100644
--- a/Documentation/lei-init.pod
+++ b/Documentation/lei-init.pod
@@ -17,7 +17,9 @@ location.
 
 =over
 
-=item -q, --quiet
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
diff --git a/Documentation/lei-ls-external.pod b/Documentation/lei-ls-external.pod
index 124b7763..4c0c263d 100644
--- a/Documentation/lei-ls-external.pod
+++ b/Documentation/lei-ls-external.pod
@@ -15,7 +15,9 @@ to matching entries.
 
 =over
 
-=item -g, --globoff
+=item -g
+
+=item --globoff
 
 Do not match C<FILTER> using C<*?> wildcards and C<[]> ranges.
 
@@ -27,7 +29,9 @@ Limit operations to the local filesystem.
 
 Limit operations to those requiring network access.
 
-=item -z, -0
+=item -z
+
+=item -0
 
 Use C<\0> (NUL) instead of newline (CR) to delimit lines.
 
diff --git a/Documentation/lei-ls-label.pod b/Documentation/lei-ls-label.pod
index df100a24..41aa030d 100644
--- a/Documentation/lei-ls-label.pod
+++ b/Documentation/lei-ls-label.pod
@@ -14,11 +14,15 @@ List all known message labels ("mailboxes" in JMAP terminology).
 
 =over
 
-=item -z, -0
+=item -z
+
+=item -0
 
 Use C<\0> (NUL) instead of newline (CR) to delimit lines.
 
-=item -q, --quiet
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
diff --git a/Documentation/lei-p2q.pod b/Documentation/lei-p2q.pod
index fc85fa88..f404ede0 100644
--- a/Documentation/lei-p2q.pod
+++ b/Documentation/lei-p2q.pod
@@ -23,7 +23,9 @@ L<git-format-patch(1)> is used to generate the patch.
 
 =over
 
-=item -w PREFIX[,PREFIX], --want=PREFIX[,PREFIX]
+=item -w PREFIX[,PREFIX]
+
+=item --want=PREFIX[,PREFIX]
 
 Search prefixes to use.  C<dfpost> (post-image git blob ID) and C<dfn>
 (file names from the diff) are the most useful.  Other available
@@ -54,7 +56,9 @@ Dump output that shows the information collected for every prefix.
 This information can be useful for seeing how a patch is processed,
 but the format should not be considered stable.
 
-=item -q, --quiet
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
diff --git a/Documentation/lei-tag.pod b/Documentation/lei-tag.pod
index 5282b3d2..b2509ba4 100644
--- a/Documentation/lei-tag.pod
+++ b/Documentation/lei-tag.pod
@@ -26,14 +26,18 @@ specified messages, and "-L:INBOX" would remove the "INBOX" label.
 
 =over
 
-=item -F MAIL_FORMAT, --in-format=MAIL_FORMAT
+=item -F MAIL_FORMAT
+
+=item --in-format=MAIL_FORMAT
 
 Message input format: C<eml>, C<mboxrd>, C<mboxcl2>, C<mboxcl>, or
 C<mboxo>.
 
 Default: C<eml>
 
-=item -q, --quiet
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
diff --git a/Documentation/public-inbox-compact.pod b/Documentation/public-inbox-compact.pod
index cf64fe0d..d2b74c86 100644
--- a/Documentation/public-inbox-compact.pod
+++ b/Documentation/public-inbox-compact.pod
@@ -34,7 +34,11 @@ Compact all inboxes configured in ~/.public-inbox/config.
 This is an alternative to specifying individual inboxes directories
 on the command-line.
 
-=item --blocksize / --no-full / --fuller
+=item --blocksize
+
+=item --no-full
+
+=item --fuller
 
 These options are passed directly to L<xapian-compact(1)>.
 
diff --git a/Documentation/public-inbox-convert.pod b/Documentation/public-inbox-convert.pod
index b8c8d54f..a2f8caf5 100644
--- a/Documentation/public-inbox-convert.pod
+++ b/Documentation/public-inbox-convert.pod
@@ -25,7 +25,9 @@ By default, public-inbox-convert creates a new index in the
 v2 inbox and indexes all existing messages, a lengthy
 operation for large inboxes.
 
-=item -j JOBS, --jobs=JOBS
+=item -j JOBS
+
+=item --jobs=JOBS
 
 Control the number of indexing jobs and Xapian shards of the v2
 inbox.  By default, this is the detected CPU count but capped
diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod
index 3bf95496..ec210efa 100644
--- a/Documentation/public-inbox-daemon.pod
+++ b/Documentation/public-inbox-daemon.pod
@@ -28,7 +28,9 @@ processes to take advantage of multiple CPUs.
 
 =over
 
-=item -l, --listen ADDRESS
+=item -l ADDRESS
+
+=item --listen ADDRESS
 
 This takes an absolute path to a Unix socket or HOST:PORT
 to listen on.  For example, to listen to TCP connections on
@@ -45,7 +47,9 @@ L<systemd.socket(5)> or similar
 Default: server-dependent unless socket activation is used with
 L<systemd(1)> or similar (see L<systemd.socket(5)>).
 
-=item -1, --stdout PATH
+=item -1
+
+=item --stdout PATH
 
 Specify an appendable path to redirect stdout descriptor (1) to.
 Using this is preferable to setting up the redirect externally
@@ -54,11 +58,15 @@ SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
 
 Default: /dev/null
 
-=item -2, --stderr PATH
+=item -2 PATH
+
+=item --stderr PATH
 
 Like C<--stdout>, but for the stderr descriptor (2).
 
-=item -W, --worker-processes
+=item -W
+
+=item --worker-processes
 
 Set the number of worker processes.
 
diff --git a/Documentation/public-inbox-extindex.pod b/Documentation/public-inbox-extindex.pod
index bed65272..fed5017b 100644
--- a/Documentation/public-inbox-extindex.pod
+++ b/Documentation/public-inbox-extindex.pod
@@ -23,7 +23,9 @@ along with L<DBD::SQLite> and L<DBI> Perl modules.
 
 =over
 
-=item --jobs=JOBS, -j
+=item -j JOBS
+
+=item --jobs=JOBS
 
 ... TODO, see L<public-inbox-index(5)>
 
diff --git a/Documentation/public-inbox-imapd.pod b/Documentation/public-inbox-imapd.pod
index 71e0ea7f..52df4d51 100644
--- a/Documentation/public-inbox-imapd.pod
+++ b/Documentation/public-inbox-imapd.pod
@@ -27,7 +27,9 @@ are supported and documented below.
 
 =over
 
-=item -l, --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+=item -l PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+
+=item --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
 
 In addition to the normal C<-l>/C<--listen> switch described in
 L<public-inbox-daemon(8)>, the C<PROTO> prefix (e.g. C<imap://> or
diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod
index 3bdd5efc..57fedb69 100644
--- a/Documentation/public-inbox-index.pod
+++ b/Documentation/public-inbox-index.pod
@@ -34,7 +34,9 @@ normal search functionality.
 
 =over
 
-=item --jobs=JOBS, -j
+=item -j JOBS
+
+=item --jobs=JOBS
 
 Influences the number of Xapian indexing shards in a
 (L<public-inbox-v2-format(5)>) inbox.
@@ -52,7 +54,9 @@ the overview and article number mapping).
 
 Default: the number of existing Xapian shards
 
-=item --compact / -c
+=item -c
+
+=item --compact
 
 Compacts the Xapian DBs after indexing.  This is recommended
 when using C<--reindex> to avoid running out of disk space
@@ -162,7 +166,9 @@ See L<public-inbox-init(1)/--skip-docdata> for description and caveats.
 
 Available in public-inbox 1.6.0+.
 
-=item --update-extindex=EXTINDEX, -E
+=item -E EXTINDEX
+
+=item --update-extindex=EXTINDEX
 
 Update the given external index (L<public-inbox-extindex-format(5)>.
 Either the configured section name (e.g. C<all>) or a directory name
diff --git a/Documentation/public-inbox-init.pod b/Documentation/public-inbox-init.pod
index 5a875f9d..62624f14 100644
--- a/Documentation/public-inbox-init.pod
+++ b/Documentation/public-inbox-init.pod
@@ -20,7 +20,9 @@ may be specified for inboxes with multiple addresses.
 
 =over
 
-=item -V, --version FORMAT_VERSION
+=item -V FORMAT_VERSION
+
+=item --version FORMAT_VERSION
 
 Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
 if you have L<DBD::SQLite> installed.
@@ -31,7 +33,9 @@ L<DBD::SQLite>.
 
 Default: C<1>
 
-=item -L, --indexlevel <basic|medium|full>
+=item -L <basic|medium|full>
+
+=item --indexlevel <basic|medium|full>
 
 Controls the indexing level for L<public-inbox-index(1)>
 
@@ -39,7 +43,9 @@ See L<public-inbox-config(5)> for more information.
 
 Default: C<full>
 
-=item --ng, --newsgroup NEWSGROUP
+=item --ng NEWSGROUP
+
+=item --newsgroup NEWSGROUP
 
 The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
 may be any newsgroup name with hierarchies delimited by C<.>.
@@ -70,7 +76,9 @@ Available in public-inbox 1.6.0+.
 
 Default: unset, no NNTP article numbers are skipped
 
-=item -S, --skip-epoch
+=item -S
+
+=item --skip-epoch
 
 For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
 allows archivists to publish incomplete archives with newer
@@ -81,7 +89,9 @@ Available since public-inbox 1.2.0.
 
 Default: unset, no epochs are skipped
 
-=item -j, --jobs=JOBS
+=item -j JOBS
+
+=item --jobs=JOBS
 
 Control the number of Xapian index shards in a
 C<-V2> (L<public-inbox-v2-format(5)>) inbox.
diff --git a/Documentation/public-inbox-nntpd.pod b/Documentation/public-inbox-nntpd.pod
index 83f7c83a..651428ab 100644
--- a/Documentation/public-inbox-nntpd.pod
+++ b/Documentation/public-inbox-nntpd.pod
@@ -26,7 +26,9 @@ are supported and documented below.
 
 =over
 
-=item -l, --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+=item -l PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+
+=item --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
 
 In addition to the normal C<-l>/C<--listen> switch described in
 L<public-inbox-daemon(8)>, the protocol prefix (e.g. C<nntp://> or
diff --git a/Documentation/public-inbox-xcpdb.pod b/Documentation/public-inbox-xcpdb.pod
index eb675965..e7c07ed3 100644
--- a/Documentation/public-inbox-xcpdb.pod
+++ b/Documentation/public-inbox-xcpdb.pod
@@ -30,7 +30,9 @@ Copy all inboxes configured in ~/.public-inbox/config.
 This is an alternative to specifying individual inboxes directories
 on the command-line.
 
-=item -c, --compact
+=item -c
+
+=item --compact
 
 In addition to performing the copy operation, run L<xapian-compact(1)>
 on each Xapian shard after copying but before finalizing it.
@@ -42,7 +44,9 @@ preferable for gigantic inboxes where the coarse-grained lock
 currently required for L<public-inbox-compact(1)> can cause
 the compaction to take hours at-a-time.
 
-=item --reshard=N / -R N
+=item -R N
+
+=item --reshard=N
 
 Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
 inbox to C<N> shards .  Since L<xapian-compact(1)> is not suitable
@@ -52,7 +56,11 @@ existing Xapian database(s) to any positive value of C<N>.
 This is useful in case the Xapian DB was created with too few or
 too many shards given the capabilities of the current hardware.
 
-=item --blocksize / --no-full / --fuller
+=item --blocksize
+
+=item --no-full
+
+=item --fuller
 
 These options are passed directly to L<xapian-compact(1)> when
 used with C<--compact>.
-- 
2.31.1

[PATCH 3/9] doc lei blob: point to lei-q for shared options

[Kyle Meyer]

lei-blob shares a good number of options with lei-q.  Refer to lei-q's
manpage rather than repeating the descriptions.

Also, add lei-q to lei-blob's "see also" section.

Link: https://public-inbox.org/meta/YGFImEcWX1mCJJwv@dcvr/
---
 Documentation/lei-blob.pod | 47 ++++++++++----------------------------
 1 file changed, 12 insertions(+), 35 deletions(-)

diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 76918324..36c75d53 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -49,60 +49,37 @@ Provide pre-image pathname as a hint for reconstructing C<OID>.
 
 Provide post-image pathname as a hint for reconstructing C<OID>.
 
-=for comment
-TODO: The below options are shared with lei-q.  Any good approaches to
-not repeating the text?
+=item -v
 
-=item --[no-]remote
+=item --verbose
 
-Whether to include results requiring network access.  When local
-externals are configured, C<--remote> must be explicitly passed to
-enable reporting of results from remote externals.
+Provide more feedback on stderr.
 
-=item --no-local
+=back
 
-Limit operations to those requiring network access.
+The following options are also supported and are described in
+L<lei-q(1)>.
 
-=item --no-external
+=over
 
-Don't include results from externals.
+=item --[no-]remote
 
-=item -I LOCATION
+=item --no-local
 
-=item --include=LOCATION
+=item --no-external
 
-Include specified external in search.  This option may be given
-multiple times.
+=item -I LOCATION, --include=LOCATION
 
 =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 --no-import-remote
 
-Disable the default behavior of memoizing remote messages into the
-local store.
-
-=item -v
-
-=item --verbose
-
-Provide more feedback on stderr.
-
 =item --torsocks=auto|no|yes
 
 =item --no-torsocks
 
-Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
-
-Default: C<auto>
-
 =back
 
 =head1 CONTACT
@@ -121,4 +98,4 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
-L<lei-add-external(1)>
+L<lei-add-external(1)>, L<lei-q(1)>
-- 
2.31.1

[PATCH 4/9] doc lei: resort lei-tag entries

[Kyle Meyer]

The command was renamed in 54da988cfb049ea2 (lei tag: rename from "lei
mark", 2021-03-30).  Relocate its entries in txt2pre and Makefile.PL
to restore alphabetical sorting.
---
 Documentation/txt2pre | 2 +-
 Makefile.PL           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 7b9d7853..25d81cf9 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -21,10 +21,10 @@ for (qw[lei(1)
 	lei-init(1)
 	lei-ls-external(1)
 	lei-ls-label(1)
-	lei-tag(1)
 	lei-overview(7)
 	lei-p2q(1)
 	lei-q(1)
+	lei-tag(1)
 	public-inbox.cgi(1)
 	public-inbox-compact(1)
 	public-inbox-config(5)
diff --git a/Makefile.PL b/Makefile.PL
index 401c033e..b06b6ab8 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -47,7 +47,7 @@ $v->{-m1} = [ map {
 	qw(
 	lei-add-external lei-blob lei-config lei-daemon-kill lei-daemon-pid
 	lei-forget-external lei-import lei-init lei-ls-external lei-ls-label
-	lei-tag lei-p2q lei-q)];
+	lei-p2q lei-q lei-tag)];
 $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
 		public-inbox-v2-format public-inbox-extindex-format
 		lei-mail-formats lei-store-format
-- 
2.31.1

[PATCH 5/9] doc lei q: fix a typo

[Kyle Meyer]

---
 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 46884aa5..e1c20a0d 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -99,7 +99,7 @@ Augment output destination instead of clobbering it.
 
 =item --no-import-before
 
-Do not importing keywords before writing to an existing output
+Do not import keywords before writing to an existing output
 destination.
 
 =item --threads
-- 
2.31.1

[PATCH 6/9] doc lei q: add missing value for --lock

[Kyle Meyer]

---
 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 e1c20a0d..39199849 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -171,7 +171,7 @@ option applies to C<--include>, C<--exclude>, and C<--only>.
 Disable the default behavior of memoizing remote messages into the
 local store.
 
-=item --lock
+=item --lock=METHOD
 
 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 C<none>.
-- 
2.31.1

[PATCH 7/9] doc lei: add manpage for convert

[Kyle Meyer]

Link: https://public-inbox.org/meta/20210429015738.GA30172@dcvr/
---
 Documentation/lei-convert.pod | 73 +++++++++++++++++++++++++++++++++++
 Documentation/lei.pod         |  2 +
 Documentation/txt2pre         |  1 +
 MANIFEST                      |  1 +
 Makefile.PL                   |  6 +--
 5 files changed, 80 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/lei-convert.pod

diff --git a/Documentation/lei-convert.pod b/Documentation/lei-convert.pod
new file mode 100644
index 00000000..e8a71393
--- /dev/null
+++ b/Documentation/lei-convert.pod
@@ -0,0 +1,73 @@
+=head1 NAME
+
+lei-convert - one-time conversion from URL or filesystem to another format
+
+=head1 SYNOPSIS
+
+lei convert [OPTIONS] LOCATION
+
+lei convert [OPTIONS] (--stdin|-)
+
+=head1 DESCRIPTION
+
+Convert messages to another format.  C<LOCATION> is a 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.
+
+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
+
+=over
+
+=item -F MAIL_FORMAT
+
+=item --in-format=MAIL_FORMAT
+
+Message input format.  Unless messages are given on stdin, using a
+format prefix with C<LOCATION> is preferred.
+
+=back
+
+The following options are also supported and are described in
+L<lei-q(1)>.
+
+=over
+
+=item -o MFOLDER, --output=MFOLDER
+
+=item --lock METHOD
+
+=item --no-kw
+
+=item --no-import-remote
+
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
+
+=item --proxy=PROTO://HOST[:PORT]
+
+=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.pod b/Documentation/lei.pod
index 58646577..78e1fb1e 100644
--- a/Documentation/lei.pod
+++ b/Documentation/lei.pod
@@ -84,6 +84,8 @@ Other subcommands include
 
 =item * L<lei-config(1)>
 
+=item * L<lei-convert(1)>
+
 =item * L<lei-daemon-kill(1)>
 
 =item * L<lei-daemon-pid(1)>
diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 25d81cf9..201566ee 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -14,6 +14,7 @@ for (qw[lei(1)
 	lei-add-external(1)
 	lei-blob(1)
 	lei-config(1)
+	lei-convert(1)
 	lei-daemon-kill(1)
 	lei-daemon-pid(1)
 	lei-forget-external(1)
diff --git a/MANIFEST b/MANIFEST
index a6d94c77..29e62880 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -24,6 +24,7 @@ Documentation/include.mk
 Documentation/lei-add-external.pod
 Documentation/lei-blob.pod
 Documentation/lei-config.pod
+Documentation/lei-convert.pod
 Documentation/lei-daemon-kill.pod
 Documentation/lei-daemon-pid.pod
 Documentation/lei-forget-external.pod
diff --git a/Makefile.PL b/Makefile.PL
index b06b6ab8..d149a164 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -45,9 +45,9 @@ $v->{-m1} = [ map {
 		}
 	} @EXE_FILES,
 	qw(
-	lei-add-external lei-blob lei-config lei-daemon-kill lei-daemon-pid
-	lei-forget-external lei-import lei-init lei-ls-external lei-ls-label
-	lei-p2q lei-q lei-tag)];
+	lei-add-external lei-blob lei-config lei-convert lei-daemon-kill
+	lei-daemon-pid lei-forget-external lei-import lei-init lei-ls-external
+	lei-ls-label lei-p2q lei-q lei-tag)];
 $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
 		public-inbox-v2-format public-inbox-extindex-format
 		lei-mail-formats lei-store-format
-- 
2.31.1

[PATCH 8/9] doc lei: add manpages for new commands

[Kyle Meyer]

---
 Documentation/lei-edit-search.pod   | 28 ++++++++++
 Documentation/lei-forget-search.pod | 28 ++++++++++
 Documentation/lei-lcat.pod          | 79 +++++++++++++++++++++++++++++
 Documentation/lei-ls-mail-sync.pod  | 55 ++++++++++++++++++++
 Documentation/lei-ls-search.pod     | 65 ++++++++++++++++++++++++
 Documentation/lei-overview.pod      | 12 +++++
 Documentation/lei-q.pod             |  2 +-
 Documentation/lei-rediff.pod        | 79 +++++++++++++++++++++++++++++
 Documentation/lei-up.pod            | 48 ++++++++++++++++++
 Documentation/lei.pod               | 16 ++++++
 Documentation/txt2pre               |  8 +++
 MANIFEST                            |  7 +++
 Makefile.PL                         |  8 +--
 13 files changed, 431 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/lei-edit-search.pod
 create mode 100644 Documentation/lei-forget-search.pod
 create mode 100644 Documentation/lei-lcat.pod
 create mode 100644 Documentation/lei-ls-mail-sync.pod
 create mode 100644 Documentation/lei-ls-search.pod
 create mode 100644 Documentation/lei-rediff.pod
 create mode 100644 Documentation/lei-up.pod

diff --git a/Documentation/lei-edit-search.pod b/Documentation/lei-edit-search.pod
new file mode 100644
index 00000000..7908b5a2
--- /dev/null
+++ b/Documentation/lei-edit-search.pod
@@ -0,0 +1,28 @@
+=head1 NAME
+
+lei-edit-search - edit saved search
+
+=head1 SYNOPSIS
+
+lei edit-search [OPTIONS] OUTPUT
+
+=head1 DESCRIPTION
+
+Invoke C<git config --edit> to edit the saved search at C<OUTPUT>.
+
+=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-ls-search(1)>, L<lei-forget-search(1)>, L<lei-up(1)>, L<lei-q(1)>
diff --git a/Documentation/lei-forget-search.pod b/Documentation/lei-forget-search.pod
new file mode 100644
index 00000000..49bc1d68
--- /dev/null
+++ b/Documentation/lei-forget-search.pod
@@ -0,0 +1,28 @@
+=head1 NAME
+
+lei-forget-search - forget saved search
+
+=head1 SYNOPSIS
+
+lei forget-search [OPTIONS] OUTPUT
+
+=head1 DESCRIPTION
+
+Forget a saved search at C<OUTPUT>.
+
+=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-edit-search(1)>, L<lei-ls-search(1)>, L<lei-up(1)>, L<lei-q(1)>
diff --git a/Documentation/lei-lcat.pod b/Documentation/lei-lcat.pod
new file mode 100644
index 00000000..5a2bdb5a
--- /dev/null
+++ b/Documentation/lei-lcat.pod
@@ -0,0 +1,79 @@
+=head1 NAME
+
+lei-lcat - display local copy of messages(s)
+
+=head1 SYNOPSIS
+
+lei lcat [OPTIONS] MSGID_OR_URL [MSGID_OR_URL...]
+
+lei lcat [OPTIONS] (--stdin|-)
+
+=head1 DESCRIPTION
+
+lcat (local cat) is a wrapper around L<lei-q(1)> that displays local
+messages by Message-ID.  It is able to extract Message-IDs from URLs
+as well as from common formats such as C<E<lt>$MSGIDE<gt>> and
+C<id:$MSGID>.  When reading from stdin, input that isn't understood is
+discarded, so the caller doesn't have to bother extracting the
+Message-ID or link from surrounding text (e.g., a "Link: $URL" line).
+
+=head1 OPTIONS
+
+The following options, described in L<lei-q(1)>, are supported.
+
+=over
+
+=item --[no-]remote
+
+=item --no-local
+
+=item --no-external
+
+=item --no-import-remote
+
+=item --torsocks=auto|no|yes, --no-torsocks
+
+=item --proxy=PROTO://HOST[:PORT]
+
+=item -o MFOLDER, --output=MFOLDER
+
+=item -d STRATEGY, --dedupe=STRATEGY
+
+=item -t, --threads
+
+=item -s KEY, --sort=KEY
+
+=item -r, --reverse
+
+=item --offset=NUMBER
+
+=item -g, --globoff
+
+=item -a, --augment
+
+=item --lock=METHOD
+
+=item --alert=COMMAND
+
+=item --mua=COMMAND
+
+=item --no-color
+
+=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-q(1)>, L<lei-blob(1)>
diff --git a/Documentation/lei-ls-mail-sync.pod b/Documentation/lei-ls-mail-sync.pod
new file mode 100644
index 00000000..37aa910f
--- /dev/null
+++ b/Documentation/lei-ls-mail-sync.pod
@@ -0,0 +1,55 @@
+=head1 NAME
+
+lei-ls-mail-sync - list mail sync folders
+
+=head1 SYNOPSIS
+
+lei mail-sync [OPTIONS] [FILTER]
+
+=head1 DESCRIPTION
+
+List mail sync folders.  If C<FILTER> is given, restrict the output to
+matching entries.
+
+=head1 OPTIONS
+
+=over
+
+=item -g
+
+=item --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
+
+=item -0
+
+Use C<\0> (NUL) instead of newline (CR) to delimit lines.
+
+=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-q(1)>, L<lei-up(1)>
diff --git a/Documentation/lei-ls-search.pod b/Documentation/lei-ls-search.pod
new file mode 100644
index 00000000..138dbbff
--- /dev/null
+++ b/Documentation/lei-ls-search.pod
@@ -0,0 +1,65 @@
+=head1 NAME
+
+lei-ls-search - list saved search queries
+
+=head1 SYNOPSIS
+
+lei ls-search [OPTIONS] [PREFIX]
+
+=head1 DESCRIPTION
+
+List saved search queries.  If C<PREFIX> is given, restrict the output
+to entries that start with the specified value.
+
+=head1 OPTIONS
+
+=over
+
+=item -f FORMAT
+
+=item --format=FORMAT
+
+Display JSON output rather than default short output that includes
+only the saved search location.  Possible values are C<json>,
+C<jsonl>, or C<concatjson>.
+
+=item --pretty
+
+Pretty print C<json> or C<concatjson> output.  If stdout is opened to
+a tty and used as the C<--output> destination, C<--pretty> is enabled
+by default.
+
+=item -l
+
+Long listing format (shortcut for C<--format=json>).
+
+=item --ascii
+
+Escape non-ASCII characters.
+
+=item -z
+
+=item -0
+
+Use C<\0> (NUL) instead of newline (CR) to delimit lines.  This option
+is incompatible with C<--format>.
+
+=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-q(1)>, L<lei-up(1)>, L<lei-edit-search(1)>,
+L<lei-forget-search(1)>
diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index 4a34bc16..e80cb094 100644
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -98,6 +98,18 @@ 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 -
+
+Display a local message for the public-inbox link contained in a
+commit message.
+
+=item $ lei q -f text m:MID | 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
+requires the current working directory to be within the associated
+code repository.
+
 =back
 
 =head1 PERFORMANCE NOTES
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 39199849..c4a7eea3 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -246,5 +246,5 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
-L<lei-add-external(1)>,
+L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>
diff --git a/Documentation/lei-rediff.pod b/Documentation/lei-rediff.pod
new file mode 100644
index 00000000..5fdde230
--- /dev/null
+++ b/Documentation/lei-rediff.pod
@@ -0,0 +1,79 @@
+=head1 NAME
+
+lei-rediff - regenerate a diff with different options
+
+=head1 SYNOPSIS
+
+lei rediff [OPTIONS] LOCATION [LOCATION...]
+
+lei rediff [OPTIONS] (--stdin|-)
+
+=head1 DESCRIPTION
+
+Read a message from C<LOCATION> or stdin and regenerate its diff with
+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).
+
+=head1 OPTIONS
+
+In addition to many L<git-diff(1)>, the following options are
+supported.
+
+=over
+
+=item --stdin
+
+Read message from stdin.
+
+=item --git-dir=DIR
+
+Specify an additional .git/ directory to scan.  This option may be
+given multiple times.
+
+=item --no-cwd
+
+Do not look in the git repository of the current working directory.
+
+=item -v
+
+=item --verbose
+
+Provide more feedback on stderr.
+
+=back
+
+The options below, described in L<lei-q(1)>, are also supported.
+
+=over
+
+=item --[no-]remote
+
+=item --no-local
+
+=item --no-external
+
+=item --no-import-remote
+
+=item --torsocks=auto|no|yes, --no-torsocks
+
+=item --proxy=PROTO://HOST[:PORT]
+
+=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-q(1)>, L<lei-blob(1)>, L<lei-p2q(1)>
diff --git a/Documentation/lei-up.pod b/Documentation/lei-up.pod
new file mode 100644
index 00000000..cea0f619
--- /dev/null
+++ b/Documentation/lei-up.pod
@@ -0,0 +1,48 @@
+=head1 NAME
+
+lei-up - update a saved search
+
+=head1 SYNOPSIS
+
+lei up [OPTIONS] OUTPUT
+
+lei up [OPTIONS] --all=TYPE
+
+=head1 DESCRIPTION
+
+Update the saved search at C<OUTPUT> or all saved searches of C<TYPE>
+(currently C<local> is the only supported value).
+
+=head1 OPTIONS
+
+The following options, described in L<lei-q(1)>, are supported.
+
+=over
+
+=item --lock=METHOD
+
+=item --alert=CMD
+
+=item --mua=CMD
+
+This option is incompatible with C<--all>.
+
+=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-q(1)>, L<lei-ls-search(1)>, L<lei-edit-search(1)>,
+L<lei-forget-search(1)>
diff --git a/Documentation/lei.pod b/Documentation/lei.pod
index 78e1fb1e..3af9e2ee 100644
--- a/Documentation/lei.pod
+++ b/Documentation/lei.pod
@@ -72,10 +72,24 @@ store and configured externals are
 
 =item * L<lei-blob(1)>
 
+=item * L<lei-config(1)>
+
+=item * L<lei-edit-search(1)>
+
+=item * L<lei-forget-search(1)>
+
+=item * L<lei-lcat(1)>
+
+=item * L<lei-ls-search(1)>
+
 =item * L<lei-p2q(1)>
 
 =item * L<lei-q(1)>
 
+=item * L<lei-rediff(1)>
+
+=item * L<lei-up(1)>
+
 =back
 
 Other subcommands include
@@ -92,6 +106,8 @@ Other subcommands include
 
 =item * L<lei-ls-label(1)>
 
+=item * L<lei-ls-mail-sync(1)>
+
 =back
 
 =head1 FILES
diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 201566ee..d98dfdd3 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -17,15 +17,22 @@ for (qw[lei(1)
 	lei-convert(1)
 	lei-daemon-kill(1)
 	lei-daemon-pid(1)
+	lei-edit-search(1)
 	lei-forget-external(1)
+	lei-forget-search(1)
 	lei-import(1)
 	lei-init(1)
+	lei-lcat(1)
 	lei-ls-external(1)
 	lei-ls-label(1)
+	lei-ls-mail-sync(1)
+	lei-ls-search(1)
 	lei-overview(7)
 	lei-p2q(1)
 	lei-q(1)
+	lei-rediff(1)
 	lei-tag(1)
+	lei-up(1)
 	public-inbox.cgi(1)
 	public-inbox-compact(1)
 	public-inbox-config(5)
@@ -68,6 +75,7 @@ for (qw[git(1)
 	git-config(1)
 	git-credential(1)
 	git-daemon(1)
+	git-diff(1)
 	git-fast-import(1)
 	git-fetch(1)
 	git-filter-branch(1)
diff --git a/MANIFEST b/MANIFEST
index 29e62880..c7084671 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -23,21 +23,28 @@ Documentation/hosted.txt
 Documentation/include.mk
 Documentation/lei-add-external.pod
 Documentation/lei-blob.pod
+Documentation/lei-cat.pod
 Documentation/lei-config.pod
 Documentation/lei-convert.pod
 Documentation/lei-daemon-kill.pod
 Documentation/lei-daemon-pid.pod
+Documentation/lei-edit-search.pod
 Documentation/lei-forget-external.pod
+Documentation/lei-forget-search.pod
 Documentation/lei-import.pod
 Documentation/lei-init.pod
 Documentation/lei-ls-external.pod
 Documentation/lei-ls-label.pod
+Documentation/lei-ls-mail-sync.pod
+Documentation/lei-ls-search.pod
 Documentation/lei-mail-formats.pod
 Documentation/lei-overview.pod
 Documentation/lei-p2q.pod
 Documentation/lei-q.pod
+Documentation/lei-rediff.pod
 Documentation/lei-store-format.pod
 Documentation/lei-tag.pod
+Documentation/lei-up.pod
 Documentation/lei.pod
 Documentation/lei_design_notes.txt
 Documentation/marketing.txt
diff --git a/Makefile.PL b/Makefile.PL
index d149a164..2af8c2f1 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -45,9 +45,11 @@ $v->{-m1} = [ map {
 		}
 	} @EXE_FILES,
 	qw(
-	lei-add-external lei-blob lei-config lei-convert lei-daemon-kill
-	lei-daemon-pid lei-forget-external lei-import lei-init lei-ls-external
-	lei-ls-label lei-p2q lei-q lei-tag)];
+	lei-add-external lei-blob lei-config lei-convert lei-edit-search
+	lei-daemon-kill lei-daemon-pid lei-forget-external lei-forget-search
+	lei-import lei-init lei-lcat lei-ls-external lei-ls-label
+	lei-ls-mail-sync lei-ls-search lei-p2q lei-q lei-rediff lei-tag
+	lei-up)];
 $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
 		public-inbox-v2-format public-inbox-extindex-format
 		lei-mail-formats lei-store-format
-- 
2.31.1

[PATCH 9/9] doc lei: update manpages with new options

[Kyle Meyer]

---
 Documentation/lei-blob.pod   |  2 ++
 Documentation/lei-import.pod | 16 ++++++++++++++++
 Documentation/lei-q.pod      | 10 ++++++++++
 3 files changed, 28 insertions(+)

diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 36c75d53..5b611d11 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -80,6 +80,8 @@ L<lei-q(1)>.
 
 =item --no-torsocks
 
+=item --proxy=PROTO://HOST[:PORT]
+
 =back
 
 =head1 CONTACT
diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 1fe2dac3..c29a085b 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -46,6 +46,22 @@ Default: fcntl,dotlock
 
 Don't import message keywords (or "flags" in IMAP terminology).
 
+=item --no-incremental
+
+Import already seen IMAP and NNTP articles.
+
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
+
+Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
+
+Default: C<auto>
+
+=item --proxy=PROTO://HOST[:PORT]
+
+Use the specified proxy (e.g., C<socks5h://0:9050>).
+
 =back
 
 =head1 CONTACT
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index c4a7eea3..fbe61920 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -26,6 +26,10 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
+=item --save
+
+Save a search for L<lei-up(1)>.
+
 =item --output=MFOLDER
 
 =item -o MFOLDER
@@ -66,6 +70,10 @@ default destination (stdout).
 Using a C<format:> prefix with the C<--output> destination is
 preferred when not writing to stdout.
 
+=item --no-color
+
+Disable color (for C<--format=text>).
+
 =item --pretty
 
 Pretty print C<json> or C<concatjson> output.  If stdout is opened to
@@ -229,6 +237,8 @@ Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
 Default: C<auto>
 
+=item --proxy=PROTO://HOST[:PORT]
+
 =back
 
 =head1 CONTACT
-- 
2.31.1

Re: [PATCH 8/9] doc lei: add manpages for new commands

[Eric Wong]

Kyle Meyer <kyle@kyleam.com> wrote:

Thanks, pushed this series out and your lcat fix as
commit 94be0536ce5eaf1d5a67f217dce112607624389c
("lei lcat: fix handling of multiple MSGID_OR_URL arguments")

> diff --git a/MANIFEST b/MANIFEST
> index 29e62880..c7084671 100644
> --- a/MANIFEST
> +++ b/MANIFEST
> @@ -23,21 +23,28 @@ Documentation/hosted.txt
>  Documentation/include.mk
>  Documentation/lei-add-external.pod
>  Documentation/lei-blob.pod
> +Documentation/lei-cat.pod

I squashed this fix in, though ('make check' revealed it):

diff -u b/MANIFEST b/MANIFEST
--- b/MANIFEST
+++ b/MANIFEST
@@ -23,7 +23,6 @@
 Documentation/include.mk
 Documentation/lei-add-external.pod
 Documentation/lei-blob.pod
-Documentation/lei-cat.pod
 Documentation/lei-config.pod
 Documentation/lei-convert.pod
 Documentation/lei-daemon-kill.pod
@@ -33,6 +32,7 @@
 Documentation/lei-forget-search.pod
 Documentation/lei-import.pod
 Documentation/lei-init.pod
+Documentation/lei-lcat.pod
 Documentation/lei-ls-external.pod
 Documentation/lei-ls-label.pod
 Documentation/lei-ls-mail-sync.pod

Re: [PATCH 8/9] doc lei: add manpages for new commands

[Kyle Meyer]

Eric Wong writes:

> I squashed this fix in, though ('make check' revealed it):

Oy, sorry about that.  Thanks for the fixup.