lei rediff: add --drq and --dequote-only

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

diff --git a/Documentation/public-inbox-init.pod b/Documentation/public-inbox-init.pod
index 5714828d9a1da509b1cf1d79d6753419bf186e5a..85c6c9e89172b25b77e35aa248f4f215cab0ca65 100644 (file)
--- a/Documentation/public-inbox-init.pod
+++ b/Documentation/public-inbox-init.pod
@@ -20,7 +20,9 @@ may be specified for inboxes with multiple addresses.
 
 =over
 
 
 =over
 

-=item -V, --version FORMAT_VERSION
+=item -V FORMAT_VERSION
+
+=item --version FORMAT_VERSION

 
 Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
 if you have L<DBD::SQLite> installed.
 
 Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
 if you have L<DBD::SQLite> installed.


@@ -31,6 +33,8 @@ L<DBD::SQLite>.
 
 Default: C<1>
 
 
 Default: C<1>
 

+=item -L <basic|medium|full>
+

 =item --indexlevel <basic|medium|full>
 
 Controls the indexing level for L<public-inbox-index(1)>
 =item --indexlevel <basic|medium|full>
 
 Controls the indexing level for L<public-inbox-index(1)>


@@ -39,7 +43,31 @@ See L<public-inbox-config(5)> for more information.
 
 Default: C<full>
 
 
 Default: C<full>
 

-=item -N, --skip-artnum
+=item --ng NEWSGROUP
+
+=item --newsgroup NEWSGROUP
+
+The NNTP group name for use with L<public-inbox-nntpd(8)>.  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>
+
+This may be set after-the-fact via C<publicinbox.$NAME.newsgroup>
+in the configuration file.  See L<public-inbox-config(5)> for more
+info.
+
+Available in public-inbox 1.6.0+.
+
+Default: none.
+
+=item -c KEY=VALUE
+
+Allow setting arbitrary configs as C<publicinbox.$NAME.$KEY>.
+This is idempotent for the same C<VALUE>, but allows setting
+multiple values for keys such as C<publicinbox.$NAME.url> and
+C<publicinbox.$NAME.watch>.
+
+=item --skip-artnum

 
 This option allows archivists to publish incomplete archives
 with only new mail while allowing NNTP article numbers
 
 This option allows archivists to publish incomplete archives
 with only new mail while allowing NNTP article numbers


@@ -51,30 +79,55 @@ but may be of use to L<public-inbox-v1-format(5)> users.
 There is no automatic way to use reserved NNTP article numbers
 when old mail is found, yet.
 
 There is no automatic way to use reserved NNTP article numbers
 when old mail is found, yet.
 

+Available in public-inbox 1.6.0+.
+

 Default: unset, no NNTP article numbers are skipped
 
 Default: unset, no NNTP article numbers are skipped
 

-=item -S, --skip-epoch
+=item -S
+
+=item --skip-epoch

 
 For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
 allows archivists to publish incomplete archives with newer
 mail while allowing "0.git" (or "1.git" and so on) epochs to be
 added-after-the-fact (without affecting "git clone" followers).
 
 
 For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
 allows archivists to publish incomplete archives with newer
 mail while allowing "0.git" (or "1.git" and so on) epochs to be
 added-after-the-fact (without affecting "git clone" followers).
 

+Available since public-inbox 1.2.0.
+

 Default: unset, no epochs are skipped
 
 Default: unset, no epochs are skipped
 

-=item -j, --jobs=JOBS
+=item -j JOBS
+
+=item --jobs=JOBS

 
 Control the number of Xapian index shards in a
 C<-V2> (L<public-inbox-v2-format(5)>) inbox.
 
 
 Control the number of Xapian index shards in a
 C<-V2> (L<public-inbox-v2-format(5)>) inbox.
 

-It is useful to use a single shard (C<-j1>) for inboxes on
+It can be useful to use a single shard (C<-j1>) for inboxes on

 high-latency storage (e.g. rotational HDD) unless the system has
 enough RAM to cache 5-10x the size of the git repository.
 
 high-latency storage (e.g. rotational HDD) unless the system has
 enough RAM to cache 5-10x the size of the git repository.
 

-It is generally not useful to specify higher values than the
-default due to contention in the top-level producer process.
+Another approach for HDDs is to use the
+L<public-inbox-index(1)/publicInbox.indexSequentialShard> option
+and many shards, so each shard may fit into the kernel page
+cache.  Unfortunately, excessive shards slows down read-only
+query performance.
+
+For fast storage, it is generally not useful to specify higher
+values than the default due to the top-level producer process
+being a bottleneck.

 
 

-Default: the number of online CPUs, up to 4
+Default: the number of online CPUs, up to 4 (3 shard workers, 1 producer)
+
+=item --skip-docdata
+
+Do not store document data in Xapian, reducing Xapian storage
+overhead by around 1.5%.
+
+Warning: this option prevents rollbacks to public-inbox 1.5.0
+and earlier.
+
+Available in public-inbox 1.6.0+.

 
 =back
 
 
 =back
 


@@ -90,21 +143,23 @@ Used to override the default C<~/.public-inbox/config> value.
 
 =head1 LIMITATIONS
 
 
 =head1 LIMITATIONS
 

-This tool predates NNTP support in public-inbox and is missing
-C<newsgroup> and many of the options documented in
-L<public-inbox-config(5)>.  See L<public-inbox-config(5)> for all the
-options which may be applied to a given inbox.
+Some of the options documented in L<public-inbox-config(5)>
+require editing the config file.  Old versions lack the
+C<--ng>/C<--newsgroup> parameter
+
+See L<public-inbox-config(5)> for all the options which may be applied
+to a given inbox.

 
 =head1 CONTACT
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 
 
 =head1 CONTACT
 
 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
 
 
 =head1 COPYRIGHT
 

-Copyright 2019-2020 all contributors L<mailto:meta@public-inbox.org>
+Copyright 2019-2021 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>