From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00 shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 301201FA17 for ; Thu, 27 Aug 2020 12:17:08 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH 7/8] doc: move watch config docs to -watch manpage Date: Thu, 27 Aug 2020 12:17:05 +0000 Message-Id: <20200827121706.4545-8-e@yhbt.net> In-Reply-To: <20200827121706.4545-1-e@yhbt.net> References: <20200827121706.4545-1-e@yhbt.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: The -config manpage is a bit long and the -watch stuff is isolated from the rest of it while we start documenting NNTP and IMAP support. I'm not entirely happy with the way IMAP and NNTP are configured, it's still good enough for small setups. This also fixes a long-standing misplaced comment about `publicinboxwatch.spamcheck' affecting all configured inboxes, that comment was actually for `publicinboxwatch.watchspam'. We'll omit documenting NNTP for `watchspam', for now, given the lack of \Seen flags in NNTP and I'm not sure if it's even useful. There may not be any newsgroups for sharing confirmed spam, either... --- Documentation/public-inbox-config.pod | 38 ++--------------- Documentation/public-inbox-watch.pod | 61 ++++++++++++++++++++++----- 2 files changed, 55 insertions(+), 44 deletions(-) diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod index 1dfb926e..2d845f16 100644 --- a/Documentation/public-inbox-config.pod +++ b/Documentation/public-inbox-config.pod @@ -74,26 +74,11 @@ Default: none, optional =item publicinbox..watch -A location for L to watch. Currently, -only C paths are supported: - - [publicinbox "test"] - watch = maildir:/path/to/maildirs/.INBOX.test/ - -Default: none; only for L users +See L =item publicinbox..watchheader - [publicinbox "test"] - watchheader = List-Id: - -If specified, L 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; only for L users +See L =item publicinbox..listid @@ -204,26 +189,11 @@ Default: spamc =item publicinboxwatch.spamcheck -This may be set to C to enable the use of SpamAssassin -L for filtering spam before it is imported into git -history. Other spam filtering backends may be supported in -the future. - -This requires L, but affects all configured -public-inboxes in PI_CONFIG. - -Default: none +See L =item publicinboxwatch.watchspam -A Maildir to watch for confirmed spam messages to appear in. -Messages which appear in this folder with the (S)een Maildir flag -will be hidden from all configured inboxes based on Message-ID -and content matching. - -Messages without the (S)een Maildir flag are not considered for hiding. - -Default: none; only for L users +See L =item publicinbox.nntpserver diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod index 34e8c4f2..b07d0fb5 100644 --- a/Documentation/public-inbox-watch.pod +++ b/Documentation/public-inbox-watch.pod @@ -35,8 +35,8 @@ In ~/.public-inbox/config: =head1 DESCRIPTION -public-inbox-watch allows watching a mailbox (currently only -Maildir) for the arrival of new messages and automatically +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 @@ -48,11 +48,9 @@ of large Maildirs. Upon startup, it scans the mailbox for new messages to be imported while it was not running. -Currently, only Maildirs are supported. - -For now, IMAP users should use tools such as L -or L 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 session or as a L service. Errors are emitted to stderr. @@ -64,21 +62,64 @@ public-inbox-watch takes no command-line options. =head1 CONFIGURATION These configuration knobs should be used in the -L +L file =over 8 =item publicinbox..watch +A location to watch. public-inbox 1.5.0 and earlier only supported +C paths: + + [publicinbox "test"] + watch = maildir:/path/to/maildirs/.INBOX.test/ + +public-inbox 1.6.0 supports C, C, +C and C URLs: + + watch = nntp://news.example.com/inbox.test.group + watch = imaps://mail.example.com/INBOX.test.foo + +Default: none + =item publicinbox..watchheader + [publicinbox "test"] + watchheader = List-Id: + +If specified, L 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 +This may be set to C to enable the use of SpamAssassin +L 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 -=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, C and C URLs +are supported in public-inbox 1.6.0. -See L for documentation on them. +Default: none; only for L users + +=back =head1 SIGNALS