doc: extindex: document current behavior + knobs

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

diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
index 4a97fe3b5f6c52194fc5f079c6e03633cd428864..43e54ed42d9d561e3f4a85729c9356a60b3f027a 100644 (file)
--- a/Documentation/public-inbox-config.pod
+++ b/Documentation/public-inbox-config.pod
@@ -62,13 +62,15 @@ Default: none, optional
 
 =item publicinbox.<name>.newsgroup
 
-The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
+The NNTP group name for use with L<public-inbox-nntpd(1)>.  This
 may be any newsgroup name with hierarchies delimited by C<.>.
 For example, the newsgroup for L<mailto:meta@public-inbox.org>
 is: C<inbox.comp.mail.public-inbox.meta>
 
-Omitting this for the given inbox will prevent the group from
-being read by L<public-inbox-nntpd(1)>
+It also configures the folder hierarchy used by L<public-inbox-imapd(1)>.
+
+Omitting this for a given inbox will prevent the inbox from
+being served by L<public-inbox-nntpd(1)> and/or L<public-inbox-imapd(1)>.
 
 Default: none, optional
 
@@ -98,6 +100,12 @@ needs to match.
 
 Default: none
 
+=item publicinbox.<name>.imapmirror
+
+This may be the full IMAP URL of an independently-run IMAP mirror.
+
+Default: none
+
 =item publicinbox.<name>.nntpmirror
 
 This may be the full NNTP URL of an independently-run mirror.
@@ -124,6 +132,14 @@ allow for searching for phrases using quoted text.
 
 Default: C<full>
 
+=item publicinbox.<name>.boost
+
+Control indexing order for L<public-inbox-extindex(1)>, with ties
+broken by config file order.  This only affects indexing and does
+not affect messages which are already indexed.
+
+Default: C<0>
+
 =item publicinbox.<name>.indexSequentialShard
 
 See L<public-inbox-index(1)/publicInbox.indexSequentialShard>
@@ -195,14 +211,18 @@ See L<public-inbox-watch(1)>
 
 See L<public-inbox-watch(1)>
 
-=item publicinbox.nntpserver
+=item publicinbox.imapserver
 
-Set this to point to the hostname of the L<public-inbox-nntpd(1)>
-instance.  This is used to advertise the existence of the NNTP
+Set this to point to the hostname(s) of the L<public-inbox-imapd(1)>
+instance.  This is used to advertise the existence of the IMAP
 endpoint in the L<PublicInbox::WWW> HTML interface.
 
-Multiple values are allowed for instances with multiple hostnames
-or mirrors.
+Default: none
+
+=item publicinbox.nntpserver
+
+Same as C<publicinbox.imapserver>, but for the hostname(s) of the
+L<public-inbox-nntpd(1)> instance.
 
 Default: none
 
@@ -287,9 +307,8 @@ L<Plack::App::Cascade(3pm)>
 =item * match=domain
 - Only show inboxes with URLs which belong to the domain of the HTTP request
 
-=for TODO comment
-
-support showing cgit listing
+=for comment
+TODO support showing cgit listing
 
 =back
 
@@ -323,6 +342,38 @@ always contain all git repos used by the inbox at C<$INBOX_URL>
 
 Default: C<match=domain>
 
+=item publicinbox.<name>.obfuscate
+
+Whether to obfuscate email addresses in the L<PublicInbox::WWW> HTML
+interface.
+
+Default: false
+
+=item publicinbox.noObfuscate
+
+A space-delimited list of well-known addresses and domains that should
+not be obfuscated when C<publicinbox.$NAME.obfuscate> is true (e.g.,
+C<public@example.com> and C<@example.com>).  This may be specified
+more than once, in which case the values are merged.
+
+Default: none
+
+=item extindex.<name>.topdir
+
+The directory of an external index.  See
+L<public-inbox-extindex(1)> for more details.
+
+=item extindex.<name>.url
+
+Identical to L</publicinbox.E<lt>nameE<gt>.url>, but for
+external indices
+
+=item extindex.<name>.coderepo
+
+Identical to L</publicinbox.E<lt>nameE<gt>.coderepo>, but for
+external indices.  Code repos may be freely associated with
+any number of public inboxes and external indices.
+
 =back
 
 =head2 NAMED LIMITER (PSGI)
@@ -335,7 +386,7 @@ limiter with a low max value; while smaller inboxes can use
 the default limiter.
 
 C<RLIMIT_*> keys may be set to enforce resource limits for
-a particular limiter.
+a particular limiter (L<BSD::Resource(3pm)> is required).
 
 Default named-limiters are prefixed with "-".  Currently,
 the "-cgit" named limiter is reserved for instances spawning
@@ -407,8 +458,8 @@ Used to override the default "~/.public-inbox/config" value.
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 
-The mail archives are hosted at L<https://public-inbox.org/meta/>
-and L<http://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT