[PATCH] doc: explain publicinbox.<name>.watchheader

[PATCH] doc: explain publicinbox.<name>.watchheader

[Alyssa Ross]

It wasn't clear to me exactly what this does -- in particular, what
happens if it isn't specified?  Does it support multiple values?  A
very brief explanation can answer both of these questions without
making somebody look at the code.
---
The part about it not supporting multiple values is my best guess
based on a quick glance at the code -- I may well have missed
something.

 Documentation/public-inbox-config.pod | 3 +++
 Documentation/public-inbox-watch.pod  | 4 ++++
 2 files changed, 7 insertions(+)

diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
index 4e8ba4d..8d545f7 100644
--- a/Documentation/public-inbox-config.pod
+++ b/Documentation/public-inbox-config.pod
@@ -80,6 +80,9 @@ Default: none; only for L<public-inbox-watch(1)> users
 	[publicinbox "test"]
 		watchheader = List-Id:<test.example.com>
 
+If specified, L<public-inbox-watch(1)> will only process mail matching
+the given header.  Multiple values are not currently supported.
+
 Default: none; only for L<public-inbox-watch(1)> users
 
 =item publicinbox.<name>.nntpmirror
diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod
index 3f282f0..198c170 100644
--- a/Documentation/public-inbox-watch.pod
+++ b/Documentation/public-inbox-watch.pod
@@ -15,7 +15,11 @@ In ~/.public-inbox/config:
 		mainrepo = /path/to/test.example.com.git
 
 		; config keys specific to public-inbox-watch:
+
 		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]
-- 
2.23.0

Re: [PATCH] doc: explain publicinbox.<name>.watchheader

[Eric Wong]

Alyssa Ross <hi@alyssa.is> wrote:
> It wasn't clear to me exactly what this does -- in particular, what
> happens if it isn't specified?  Does it support multiple values?  A
> very brief explanation can answer both of these questions without
> making somebody look at the code.

Thanks, applied and pushed.

> ---
> The part about it not supporting multiple values is my best guess
> based on a quick glance at the code -- I may well have missed
> something.

That's correct.  I think a single value here is fine.
If it supported multiple values, it would be confusing as
to whether it needs to match all the headers, or if matching
any one header would put it into an inbox.

And I also question the need for either case...