From 9d72cc3f876e3d2bd1ecb2fc0f33c43a9a72b933 Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sat, 16 Oct 2021 01:39:44 -0400 Subject: [PATCH] doc: lei: add manpages for remaining commands At this point all of the current lei commands, aside from -help and -sucks, should be covered. --- Documentation/lei-add-watch.pod | 33 ++++++++++++++ Documentation/lei-forget-mail-sync.pod | 31 +++++++++++++ Documentation/lei-inspect.pod | 57 ++++++++++++++++++++++++ Documentation/lei-ls-mail-source.pod | 58 +++++++++++++++++++++++++ Documentation/lei-ls-mail-sync.pod | 2 +- Documentation/lei-ls-watch.pod | 29 +++++++++++++ Documentation/lei-mail-diff.pod | 33 ++++++++++++++ Documentation/lei-refresh-mail-sync.pod | 2 +- Documentation/lei-rm-watch.pod | 30 +++++++++++++ Documentation/lei.pod | 14 ++++++ Documentation/txt2pre | 7 +++ MANIFEST | 7 +++ Makefile.PL | 12 ++--- 13 files changed, 307 insertions(+), 8 deletions(-) create mode 100644 Documentation/lei-add-watch.pod create mode 100644 Documentation/lei-forget-mail-sync.pod create mode 100644 Documentation/lei-inspect.pod create mode 100644 Documentation/lei-ls-mail-source.pod create mode 100644 Documentation/lei-ls-watch.pod create mode 100644 Documentation/lei-mail-diff.pod create mode 100644 Documentation/lei-rm-watch.pod diff --git a/Documentation/lei-add-watch.pod b/Documentation/lei-add-watch.pod new file mode 100644 index 00000000..60984618 --- /dev/null +++ b/Documentation/lei-add-watch.pod @@ -0,0 +1,33 @@ +=head1 NAME + +lei-add-watch - watch for new messages and flag changes + +=head1 SYNOPSIS + +lei add-watch [OPTIONS] LOCATION [LOCATION...] + +=head1 DESCRIPTION + +Tell lei to watch C for new messages and flag changes. +Currently only Maildir locations are supported. + +=for comment +TODO: Document --state? Believe valid values are pause, import-ro, + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L, L diff --git a/Documentation/lei-forget-mail-sync.pod b/Documentation/lei-forget-mail-sync.pod new file mode 100644 index 00000000..e70b4d33 --- /dev/null +++ b/Documentation/lei-forget-mail-sync.pod @@ -0,0 +1,31 @@ +=head1 NAME + +lei-forget-mail-sync - forget sync information for a mail folder + +=head1 SYNOPSIS + +lei forget-mail-sync [OPTIONS] LOCATION [LOCATION...] + +=head1 DESCRIPTION + +Forget synchronization information for C, an IMAP or Maildir +folder. Note that this won't delete any messages stored in Git, +leaving C users with dangling references. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L, L diff --git a/Documentation/lei-inspect.pod b/Documentation/lei-inspect.pod new file mode 100644 index 00000000..19dd8ab5 --- /dev/null +++ b/Documentation/lei-inspect.pod @@ -0,0 +1,57 @@ +=head1 NAME + +lei-inspect - general purpose inspector + +=head1 SYNOPSIS + +lei inspect [OPTIONS] ITEM [ITEM...] + +lei inspect [OPTIONS] (--stdin|-) + +=head1 DESCRIPTION + +This is a diagnostic command that provides a general purpose inspector +of various things, including blobs, message IDs, Xapian document IDs, +and mail sync sources. + +=head1 OPTIONS + +=over + +=item -d DIR + +=item --dir=DIR + +An inboxdir, extindex topdir, or Xapian shard + +=item --pretty + +Pretty print output. If stdout is opened to a tty, C<--pretty> is +enabled by default. + +=item - + +=item --stdin + +Read message from stdin. This is implicit if no arguments are given +and stdin is a pipe or regular file. + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei-ls-mail-source.pod b/Documentation/lei-ls-mail-source.pod new file mode 100644 index 00000000..926bbe2c --- /dev/null +++ b/Documentation/lei-ls-mail-source.pod @@ -0,0 +1,58 @@ +=head1 NAME + +lei-ls-mail-source - list IMAP or NNTP mail source folders + +=head1 SYNOPSIS + +lei ls-mail-source [OPTIONS] URL + +=head1 DESCRIPTION + +List information about the IMAP or NNTP mail source at C. + +=head1 OPTIONS + +=over + +=item -z + +=item -0 + +Use C<\0> (NUL) instead of newline (CR) to delimit lines. + +=item -l + +Format output as JSON and include more information. + +=item --pretty + +Pretty print JSON output. If stdout is opened to a tty, C<--pretty> +is enabled by default. + +=item --ascii + +Escape non-ASCII characters. + +=item --url + +Show full URL of newsgroup or IMAP folder. + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei-ls-mail-sync.pod b/Documentation/lei-ls-mail-sync.pod index 86aede40..883eeead 100644 --- a/Documentation/lei-ls-mail-sync.pod +++ b/Documentation/lei-ls-mail-sync.pod @@ -52,4 +52,4 @@ License: AGPL-3.0+ L =head1 SEE ALSO -L, L +L, L diff --git a/Documentation/lei-ls-watch.pod b/Documentation/lei-ls-watch.pod new file mode 100644 index 00000000..b1681ee4 --- /dev/null +++ b/Documentation/lei-ls-watch.pod @@ -0,0 +1,29 @@ +=head1 NAME + +lei-ls-watch - list active watches + +=head1 SYNOPSIS + +lei ls-watch + +=head1 DESCRIPTION + +List locations that lei is configured to watch. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L, L diff --git a/Documentation/lei-mail-diff.pod b/Documentation/lei-mail-diff.pod new file mode 100644 index 00000000..96e49a8b --- /dev/null +++ b/Documentation/lei-mail-diff.pod @@ -0,0 +1,33 @@ +=head1 NAME + +lei-mail-diff - diff the contents of emails + +=head1 SYNOPSIS + + +lei mail-diff [OPTIONS] LOCATION + +lei mail-diff [OPTIONS] (--stdin|-) + +=head1 DESCRIPTION + +This is a diagnostic command that's useful for finding deduplication +bugs. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L diff --git a/Documentation/lei-refresh-mail-sync.pod b/Documentation/lei-refresh-mail-sync.pod index 92ca9044..65150ae3 100644 --- a/Documentation/lei-refresh-mail-sync.pod +++ b/Documentation/lei-refresh-mail-sync.pod @@ -54,4 +54,4 @@ License: AGPL-3.0+ L =head1 SEE ALSO -L, L +L, L, L diff --git a/Documentation/lei-rm-watch.pod b/Documentation/lei-rm-watch.pod new file mode 100644 index 00000000..711d7dc4 --- /dev/null +++ b/Documentation/lei-rm-watch.pod @@ -0,0 +1,30 @@ +=head1 NAME + +lei-rm-watch - stop watching locations + +=head1 SYNOPSIS + +lei rm-watch [OPTIONS] LOCATION [LOCATION...] + +=head1 DESCRIPTION + +Tell lei to stop watching C for new messages and flag +changes. Currently only Maildir locations are supported. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + + +=head1 SEE ALSO + +L, L diff --git a/Documentation/lei.pod b/Documentation/lei.pod index 63d5ee69..24a585da 100644 --- a/Documentation/lei.pod +++ b/Documentation/lei.pod @@ -96,6 +96,8 @@ Other subcommands include =over +=item * L + =item * L =item * L @@ -104,10 +106,22 @@ Other subcommands include =item * L +=item * lei-forget-mail-sync(1) + +=item * L + +=item * L + =item * L +=item * L + =item * L +=item * L + +=item * L + =back =head1 FILES diff --git a/Documentation/txt2pre b/Documentation/txt2pre index bc94d404..fb07579a 100755 --- a/Documentation/txt2pre +++ b/Documentation/txt2pre @@ -12,6 +12,7 @@ use PublicInbox::Hval qw(ascii_html); my %xurls; for (qw[lei(1) lei-add-external(1) + lei-add-watch(1) lei-blob(1) lei-config(1) lei-convert(1) @@ -19,20 +20,26 @@ for (qw[lei(1) lei-daemon-pid(1) lei-edit-search(1) lei-forget-external(1) + lei-forget-mail-sync(1) lei-forget-search(1) lei-import(1) lei-index(1) lei-init(1) + lei-inspect(1) lei-lcat(1) lei-ls-external(1) lei-ls-label(1) + lei-ls-mail-source(1) lei-ls-mail-sync(1) lei-ls-search(1) + lei-ls-watch(1) + lei-mail-diff(1) lei-overview(7) lei-p2q(1) lei-q(1) lei-rediff(1) lei-rm(1) + lei-rm-watch(1) lei-security(7) lei-store-format(5) lei-tag(1) diff --git a/MANIFEST b/MANIFEST index b89513d5..c4cc6e33 100644 --- a/MANIFEST +++ b/MANIFEST @@ -22,6 +22,7 @@ Documentation/flow.txt Documentation/hosted.txt Documentation/include.mk Documentation/lei-add-external.pod +Documentation/lei-add-watch.pod Documentation/lei-blob.pod Documentation/lei-config.pod Documentation/lei-convert.pod @@ -31,15 +32,20 @@ Documentation/lei-daemon.pod Documentation/lei-edit-search.pod Documentation/lei-export-kw.pod Documentation/lei-forget-external.pod +Documentation/lei-forget-mail-sync.pod Documentation/lei-forget-search.pod Documentation/lei-import.pod Documentation/lei-index.pod Documentation/lei-init.pod +Documentation/lei-inspect.pod Documentation/lei-lcat.pod Documentation/lei-ls-external.pod Documentation/lei-ls-label.pod +Documentation/lei-ls-mail-source.pod Documentation/lei-ls-mail-sync.pod Documentation/lei-ls-search.pod +Documentation/lei-ls-watch.pod +Documentation/lei-mail-diff.pod Documentation/lei-mail-formats.pod Documentation/lei-overview.pod Documentation/lei-p2q.pod @@ -47,6 +53,7 @@ Documentation/lei-q.pod Documentation/lei-rediff.pod Documentation/lei-refresh-mail-sync.pod Documentation/lei-rm.pod +Documentation/lei-rm-watch.pod Documentation/lei-security.pod Documentation/lei-store-format.pod Documentation/lei-tag.pod diff --git a/Makefile.PL b/Makefile.PL index 22a58bee..348a343d 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -45,13 +45,13 @@ $v->{-m1} = [ map { } } @EXE_FILES, qw( - lei-add-external lei-blob lei-config lei-convert + lei-add-external lei-add-watch lei-blob lei-config lei-convert lei-daemon-kill lei-daemon-pid lei-edit-search lei-export-kw - 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-refresh-mail-sync lei-rm lei-tag + lei-forget-external lei-forget-mail-sync lei-forget-search + lei-import lei-index lei-init lei-inspect lei-lcat + lei-ls-external lei-ls-label lei-ls-mail-source lei-ls-mail-sync + lei-ls-search lei-ls-watch lei-mail-diff lei-p2q lei-q + lei-rediff lei-refresh-mail-sync lei-rm lei-rm-watch lei-tag lei-up)]; $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format public-inbox-v2-format public-inbox-extindex-format -- 2.44.0