feed: respect feedmax, again

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

diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod
index 554346de1b7259f562368a5258a4bc225449f005..acc903921e94e8a4a641fcc6c34b62a420e06872 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] REPO_DIR

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -18,22 +18,42 @@ 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

-C<$GIT_DIR/public-inbox/> directory.  All files are expected to
+C<$REPO_DIR/public-inbox/> directory.  All files are expected to

 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.
 
 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.
 

-=item $GIT_DIR/public-inbox/msgmap.sqlite3
+=over
+
+=item $REPO_DIR/public-inbox/msgmap.sqlite3

 
 The stable NNTP article number to Message-ID mapping is
 stored in an SQLite3 database.
 
 The stable NNTP article number to Message-ID mapping is
 stored in an SQLite3 database.


@@ -44,13 +64,13 @@ 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%
 of the space of the mail stored in a packed git repository.
 
 messages.
 
 This file is relatively small, and typically less than 5%
 of the space of the mail stored in a packed git repository.
 

-=item $GIT_DIR/public-inbox/xapian*
+=item $REPO_DIR/public-inbox/xapian*

 
 The database used by L<Search::Xapian>.  This directory name is
 followed by a number indicating the index schema version this
 
 The database used by L<Search::Xapian>.  This directory name is
 followed by a number indicating the index schema version this


@@ -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
 


@@ -88,7 +111,7 @@ and L<http://hjrcffqmbrq6wope.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2016 all contributors L<mailto:meta@public-inbox.org>
+Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>

 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>