From: Eric Wong <e@yhbt.net> 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> (raw) In-Reply-To: <20200827121706.4545-1-e@yhbt.net> 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.<name>.watch -A location for L<public-inbox-watch(1)> to watch. Currently, -only C<maildir:> paths are supported: - - [publicinbox "test"] - watch = maildir:/path/to/maildirs/.INBOX.test/ - -Default: none; only for L<public-inbox-watch(1)> users +See L<public-inbox-watch(1)> =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; only for L<public-inbox-watch(1)> users +See L<public-inbox-watch(1)> =item publicinbox.<name>.listid @@ -204,26 +189,11 @@ Default: spamc =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. - -This requires L<public-inbox-watch(1)>, but affects all configured -public-inboxes in PI_CONFIG. - -Default: none +See L<public-inbox-watch(1)> =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<public-inbox-watch(1)> users +See L<public-inbox-watch(1)> =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<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. @@ -64,21 +62,64 @@ public-inbox-watch takes no command-line options. =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 +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://mail.example.com/INBOX.test.foo + +Default: none + =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 +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 -=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. -See L<public-inbox-config(5)> for documentation on them. +Default: none; only for L<public-inbox-watch(1)> users + +=back =head1 SIGNALS
next prev parent reply other threads:[~2020-08-27 12:17 UTC|newest] Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-08-27 12:16 [PATCH 0/8] mostly watch-related odds and ends Eric Wong 2020-08-27 12:16 ` [PATCH 1/8] watchmaildir: ensure I:/W:/E: prefixes in warnings Eric Wong 2020-08-27 12:17 ` [PATCH 2/8] imaptracker: preserve WAL journal_mode if set by user Eric Wong 2020-08-27 12:17 ` [PATCH 3/8] overidx: inline create_ghost sub Eric Wong 2020-08-27 12:17 ` [PATCH 4/8] doc: document graceful shutdown signals Eric Wong 2020-08-27 12:17 ` [PATCH 5/8] doc: speling fickses Eric Wong 2020-08-27 12:17 ` [PATCH 6/8] watch: imap: only remove \Seen spam Eric Wong 2020-08-27 12:17 ` Eric Wong [this message] 2020-08-27 12:17 ` [PATCH 8/8] doc: watch: expand on NNTP and IMAP-specific knobs Eric Wong 2020-08-28 4:22 ` Eric Wong
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: http://public-inbox.org/README * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200827121706.4545-8-e@yhbt.net \ --to=e@yhbt.net \ --cc=meta@public-inbox.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
user/dev discussion of public-inbox itself This inbox may be cloned and mirrored by anyone: git clone --mirror http://public-inbox.org/meta git clone --mirror http://czquwvybam4bgbro.onion/meta git clone --mirror http://hjrcffqmbrq6wope.onion/meta git clone --mirror http://ou63pmih66umazou.onion/meta # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V1 meta meta/ http://public-inbox.org/meta \ meta@public-inbox.org public-inbox-index meta Example config snippet for mirrors. Newsgroups are available over NNTP: nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta nntp://ou63pmih66umazou.onion/inbox.comp.mail.public-inbox.meta nntp://czquwvybam4bgbro.onion/inbox.comp.mail.public-inbox.meta nntp://hjrcffqmbrq6wope.onion/inbox.comp.mail.public-inbox.meta nntp://news.gmane.io/gmane.mail.public-inbox.general note: .onion URLs require Tor: https://www.torproject.org/ code repositories for the project(s) associated with this inbox: https://80x24.org/public-inbox.git AGPL code for this site: git clone https://public-inbox.org/public-inbox.git