From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS8972 85.25.103.0/24 X-Spam-Status: No, score=-2.6 required=3.0 tests=BAYES_00,RCVD_IN_XBL,SPF_FAIL, SPF_HELO_FAIL shortcircuit=no autolearn=no autolearn_force=no version=3.4.0 Received: from 80x24.org (atlantic850.dedicatedpanel.com [85.25.103.69]) by dcvr.yhbt.net (Postfix) with ESMTP id 942761F859 for ; Wed, 7 Sep 2016 21:53:15 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH] doc: flesh out public-inbox-index documentation Date: Wed, 7 Sep 2016 21:53:11 +0000 Message-Id: <20160907215311.15366-1-e@80x24.org> List-Id: And include it into the build + website --- Documentation/include.mk | 1 + Documentation/public-inbox-index.pod | 31 +++++++++++++++++++++++++++---- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/Documentation/include.mk b/Documentation/include.mk index 5154d4b..542273f 100644 --- a/Documentation/include.mk +++ b/Documentation/include.mk @@ -21,6 +21,7 @@ m1 += public-inbox-mda m1 += public-inbox-httpd m1 += public-inbox-nntpd m1 += public-inbox-watch +m1 += public-inbox-index m5 = m5 += public-inbox-config m7 = diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod index 554346d..2871f0d 100644 --- a/Documentation/public-inbox-index.pod +++ b/Documentation/public-inbox-index.pod @@ -4,7 +4,7 @@ public-inbox-index - create and update search indices =head1 SYNOPSIS -public-inbox-index GIT_DIR +public-inbox-index [OPTIONS] GIT_DIR =head1 DESCRIPTION @@ -18,13 +18,31 @@ L and L will automatically maintain them. Running this manually to update indices is only required if -relying on L to mirror an existing public-inbox. +relying on L to mirror an existing public-inbox; +or if upgrading to a new version of public-inbox using +the C<--reindex> option. Having a search and article number database is essential to running the NNTP interface, and strongly recommended for the HTTP interface as it provides thread grouping in addition to normal search functionality. +=head1 OPTIONS + +=over + +=item --reindex + +Forces a search engine re-index of all messages in the +repository. This can be used for in-place upgrades while +NNTP/HTTP server processes are utilizing the index. Keep in +mind this roughly doubles the size of the already-large +Xapian database. + +This does not touch the NNTP article number database. + +=back + =head1 FILES All public-inbox-specific files are contained within the @@ -33,6 +51,8 @@ grow in size as more messages are archived, so using compaction commands (e.g. L) is not recommended unless the list is no longer active. +=over + =item $GIT_DIR/public-inbox/msgmap.sqlite3 The stable NNTP article number to Message-ID mapping is @@ -44,7 +64,7 @@ useful for attempting recovery from copy-paste truncations of URLs containing long Message-IDs. Avoid removing this file and regenerating it; it may cause -existing NNTP readers to lose sync and miss (or duplicate) +existing NNTP readers to lose sync and miss (or see duplicate) messages. This file is relatively small, and typically less than 5% @@ -67,7 +87,10 @@ provides a cache of metadata and header information often requested by NNTP clients. This directory is large, often two to three times the size of -the objects stored in a packed git repository. +the objects stored in a packed git repository. Using the +C<--reindex> option makes it larger, still. + +=back =head1 ENVIRONMENT -- EW