doc: flesh out public-inbox-index documentation

And include it into the build + website

diff --git a/Documentation/include.mk b/Documentation/include.mk
index 5154d4b6ac82e72f72153923f49165f93548f164..542273ff4df467b094b2002935f2958be5424ba9 100644 (file)
--- 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-httpd
 m1 += public-inbox-nntpd
 m1 += public-inbox-watch

+m1 += public-inbox-index

 m5 =
 m5 += public-inbox-config
 m7 =
 m5 =
 m5 += public-inbox-config
 m7 =

diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod
index 554346de1b7259f562368a5258a4bc225449f005..2871f0dad7ba61bd80f69912db309e890b9ce190 100644 (file)
--- 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
 
 
 =head1 SYNOPSIS
 

-public-inbox-index GIT_DIR
+public-inbox-index [OPTIONS] GIT_DIR

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -18,13 +18,31 @@ L<public-inbox-mda(1)> and L<public-inbox-watch(1)> will
 automatically maintain them.
 
 Running this manually to update indices is only required if
 automatically maintain them.
 
 Running this manually to update indices is only required if

-relying on L<git-fetch(1)> to mirror an existing public-inbox.
+relying on L<git-fetch(1)> 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.
 
 
 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
 =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<xapian-compact(1)>) is not recommended unless
 the list is no longer active.
 
 commands (e.g. L<xapian-compact(1)>) 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
 =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
 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%
 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
 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
 
 
 =head1 ENVIRONMENT