watch: add --help/-h support

[public-inbox.git] / Documentation / public-inbox-watch.pod

diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod
index 3f282f0f1bbdc1310ebee9788ab8be5138eb6056..73340ec486f4accb2ac79457ea2b2fd9efa4e4c2 100644 (file)
--- a/Documentation/public-inbox-watch.pod
+++ b/Documentation/public-inbox-watch.pod
@@ -4,7 +4,7 @@ public-inbox-watch - mailbox watcher for public-inbox
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-B<public-inbox-watch>
+       public-inbox-watch

 
 In ~/.public-inbox/config:
 
 
 In ~/.public-inbox/config:
 


@@ -12,10 +12,14 @@ In ~/.public-inbox/config:
                ; generic public-inbox-config keys:
                address = test@example.com
                url = http://example.com/test
                ; generic public-inbox-config keys:
                address = test@example.com
                url = http://example.com/test

-               mainrepo = /path/to/test.example.com.git
+               inboxdir = /path/to/test.example.com.git

 
                ; config keys specific to public-inbox-watch:
 
                ; config keys specific to public-inbox-watch:

+

                watch = maildir:/path/to/maildirs/.INBOX.test/
                watch = maildir:/path/to/maildirs/.INBOX.test/

+
+               ; optional, emails that don't have a header matching
+               ; value will be skipped

                watchheader = List-Id:<test.example.com>
 
        [publicinboxwatch]
                watchheader = List-Id:<test.example.com>
 
        [publicinboxwatch]


@@ -24,16 +28,16 @@ In ~/.public-inbox/config:
 
                ; optional, emails marked as read which appear
                ; here will be trained as spam and deleted from
 
                ; optional, emails marked as read which appear
                ; here will be trained as spam and deleted from

-               ; the mainrepos of any public-inboxes which are
+               ; the inboxdirs of any public-inboxes which are

                ; configured for watch.
                ; This is global for all publicinbox.* sections
                watchspam = maildir:/path/to/maildirs/.INBOX.spam
 
 =head1 DESCRIPTION
 
                ; configured for watch.
                ; This is global for all publicinbox.* sections
                watchspam = maildir:/path/to/maildirs/.INBOX.spam
 
 =head1 DESCRIPTION
 

-public-inbox-watch allows watching a mailbox (currently only
-Maildir) for the arrival of new messages and automatically
-importing them into a public-inbox (git) repository.
+public-inbox-watch allows watching a mailbox or newsgroup
+for the arrival of new messages and automatically
+importing them into public-inbox git repositories and indices.

 public-inbox-watch is useful in situations when a user wishes to
 mirror an existing mailing list, but has no access to run
 L<public-inbox-mda(1)> on a server.  Unlike public-inbox-mda
 public-inbox-watch is useful in situations when a user wishes to
 mirror an existing mailing list, but has no access to run
 L<public-inbox-mda(1)> on a server.  Unlike public-inbox-mda


@@ -44,12 +48,9 @@ of large Maildirs.
 Upon startup, it scans the mailbox for new messages to be
 imported while it was not running.
 
 Upon startup, it scans the mailbox for new messages to be
 imported while it was not running.
 

-Currently, only Maildirs are supported and the
-L<Filesys::Notify::Simple> Perl module is required.
-
-For now, IMAP users should use tools such as L<mbsync(1)>
-or L<offlineimap(1)> to bidirectionally sync their IMAP
-folders to Maildirs for public-inbox-watch.
+As of public-inbox 1.6.0, Maildirs, IMAP folders, and NNTP
+newsgroups are supported.  Previous versions of public-inbox
+only supported Maildirs.

 
 public-inbox-watch should be run inside a L<screen(1)> session
 or as a L<systemd(1)> service.  Errors are emitted to stderr.
 
 public-inbox-watch should be run inside a L<screen(1)> session
 or as a L<systemd(1)> service.  Errors are emitted to stderr.


@@ -61,21 +62,98 @@ public-inbox-watch takes no command-line options.
 =head1 CONFIGURATION
 
 These configuration knobs should be used in the
 =head1 CONFIGURATION
 
 These configuration knobs should be used in the

-L<public-inbox-config(5)>
+L<public-inbox-config(5)> file

 
 =over 8
 
 =item publicinbox.<name>.watch
 
 
 =over 8
 
 =item publicinbox.<name>.watch
 

+A location to watch.  public-inbox 1.5.0 and earlier only supported
+C<maildir:> paths:
+
+       [publicinbox "test"]
+               watch = maildir:/path/to/maildirs/.INBOX.test/
+
+public-inbox 1.6.0 supports C<nntp://>, C<nntps://>,
+C<imap://> and C<imaps://> URLs:
+
+               watch = nntp://news.example.com/inbox.test.group
+               watch = imaps://user@mail.example.com/INBOX.test
+
+This may be specified multiple times to combine several mailboxes
+into a single public-inbox.  URLs requiring authentication
+will require L<netrc(5)> and/or L<git-credential(1)> to fill
+in the username and password.
+
+Default: none
+

 =item publicinbox.<name>.watchheader
 
 =item publicinbox.<name>.watchheader
 

+       [publicinbox "test"]
+               watchheader = List-Id:<test.example.com>
+
+If specified, L<public-inbox-watch(1)> will only process mail
+matching the given header.  If specified multiple times in
+public-inbox 1.5 or later, mail will be processed if it matches
+any of the values.  Only the last value was used in public-inbox
+1.4 and earlier.
+
+Default: none
+

 =item publicinboxwatch.spamcheck
 
 =item publicinboxwatch.spamcheck
 

+This may be set to C<spamc> to enable the use of SpamAssassin
+L<spamc(1)> for filtering spam before it is imported into git
+history.  Other spam filtering backends may be supported in
+the future.
+
+Default: none
+

 =item publicinboxwatch.watchspam
 
 =item publicinboxwatch.watchspam
 

-=back
+A Maildir to watch for confirmed spam messages to appear in.
+Messages which appear in this folder with the (S)een flag
+will be hidden from all configured inboxes based on Message-ID
+and content matching.
+
+Messages without the (S)een flag are not considered for hiding.
+This hiding affects all configured public-inboxes in PI_CONFIG.
+
+As with C<publicinbox.$NAME.watch>, C<imap://> and C<imaps://> URLs
+are supported in public-inbox 1.6.0.
+
+Default: none; only for L<public-inbox-watch(1)> users
+
+=item imap.Starttls / imap.$URL.Starttls
+
+Whether or not to use C<STARTTLS> on plain C<imap://> connections.
+
+May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
+in C<git(1)> 1.8.5+.
+
+Default: C<true>
+
+=item imap.Compress / imap.$URL.Compress
+
+Whether or not to use the IMAP COMPRESS (RFC4978) extension to
+save bandwidth.  This is not supported by all IMAP servers and
+some advertising this feature may not implement it correctly.

 
 

-See L<public-inbox-config(5)> for documentation on them.
+May be specified only for certain URLs if L<git(1)> 1.8.5+ is
+installed to use L<git-config(1)/--get-urlmatch>
+
+Default: C<false>
+
+=item nntp.Starttls / nntp.$URL.Starttls
+
+Whether or not to use C<STARTTLS> on plain C<nntp://> connections.
+
+May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
+in C<git(1)> 1.8.5+.
+
+Default: C<false> if the hostname is a Tor C<.onion>, C<true> otherwise
+
+=back

 
 =head1 SIGNALS
 
 
 =head1 SIGNALS
 


@@ -90,6 +168,11 @@ Reload the config file (default: ~/.public-inbox/config)
 Rescan all watched mailboxes.  This is done automatically after
 startup.
 
 Rescan all watched mailboxes.  This is done automatically after
 startup.
 

+=item SIGQUIT / SIGTERM / SIGINT
+
+Gracefully shut down.  In-flight messages will be stored
+and indexed.
+

 =back
 
 =head1 ENVIRONMENT
 =back
 
 =head1 ENVIRONMENT


@@ -118,7 +201,7 @@ and L<http://hjrcffqmbrq6wope.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
+Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>

 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>