Documentation/public-inbox-extindex.pod

   1 =head1 NAME
   2
   3 public-inbox-extindex - create and update external search indices
   4
   5 =head1 SYNOPSIS
   6
   7 public-inbox-extindex [OPTIONS] EXTINDEX_DIR INBOX_DIR...
   8
   9 public-inbox-extindex [OPTIONS] [EXTINDEX_DIR] --all
  10
  11 =head1 DESCRIPTION
  12
  13 FIXME: behavior not finalized  It should probably write to the
  14 config file the first time --all is used.
  15
  16 public-inbox-extindex creates and updates an external search and
  17 overview database used by the read-only public-inbox PSGI (HTTP),
  18 NNTP, and IMAP interfaces.  This requires either the
  19 L<Search::Xapian> XS bindings OR the L<Xapian> SWIG bindings,
  20 along with L<DBD::SQLite> and L<DBI> Perl modules.
  21
  22 =head1 OPTIONS
  23
  24 =over
  25
  26 =item -j JOBS
  27
  28 =item --jobs=JOBS
  29
  30 ... TODO, see L<public-inbox-index(5)>
  31
  32 =item --all
  33
  34 Index all C<publicinbox> entries in C<PI_CONFIG>.
  35
  36 C<publicinbox> entries indexed by C<public-inbox-extindex> can
  37 have full Xapian searching abilities with the per-C<publicinbox>
  38 C<indexlevel> set to C<basic> and their respective Xapian
  39 (C<xap15> or C<xapian15>) directories removed.  For multiple
  40 public-inboxes where cross-posting is common, this allows
  41 significant space savings on Xapian indices.
  42
  43 =back
  44
  45 =head1 FILES
  46
  47 L<public-inbox-extindex-format(5)>
  48
  49 =head1 CONFIGURATION
  50
  51 ... TODO, see L<public-inbox-index(5)>
  52
  53 =head1 ENVIRONMENT
  54
  55 =over 8
  56
  57 =item PI_CONFIG
  58
  59 Used to override the default "~/.public-inbox/config" value.
  60
  61 =item XAPIAN_FLUSH_THRESHOLD
  62
  63 The number of documents to update before committing changes to
  64 disk.  This environment is handled directly by Xapian, refer to
  65 Xapian API documentation for more details.
  66
  67 Setting C<XAPIAN_FLUSH_THRESHOLD> or
  68 C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
  69 L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
  70 L<public-inbox-watch(1)> tasks to wait long and unpredictable
  71 periods of time during C<--reindex>.
  72
  73 Default: none, uses C<publicinbox.indexBatchSize>
  74
  75 =back
  76
  77 =head1 UPGRADING
  78
  79 Occasionally, public-inbox will update it's schema version and
  80 require a full index by running this command.
  81
  82 =head1 CONTACT
  83
  84 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
  85
  86 The mail archives are hosted at L<https://public-inbox.org/meta/> and
  87 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
  88
  89 =head1 COPYRIGHT
  90
  91 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
  92
  93 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
  94
  95 =head1 SEE ALSO
  96
  97 L<Search::Xapian>, L<DBD::SQLite>