X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fpublic-inbox-overview.pod;h=d431857687397825363e787d53804b01adca1cfd;hb=d07ba9c30800225052d17ccca458afbfa05a8ff0;hp=2c97f876cdf0d5946c92fcabcde34bc2b8af8ded;hpb=66c6699142d95cce9e5c9d49e0498161a776cc22;p=public-inbox.git

diff --git a/Documentation/public-inbox-overview.pod b/Documentation/public-inbox-overview.pod
index 2c97f876..d4318576 100644
--- a/Documentation/public-inbox-overview.pod
+++ b/Documentation/public-inbox-overview.pod
@@ -4,7 +4,7 @@ public-inbox-overview - an overview of public-inbox
 
 =head1 DESCRIPTION
 
-public-inbox consists of many parts which may be used
+public-inbox consists of many pieces which may be used
 independently or in conjunction of each other for:
 
 =over 4
@@ -15,11 +15,11 @@ Mirroring existing public-inboxes.
 
 =item 2
 
-Mirroring mailing lists directly.
+Mirroring mailing lists.
 
 =item 3
 
-Hosting standalone.
+Hosting standalone inboxes.
 
 =back
 
@@ -30,35 +30,52 @@ started.  Your mirror will remain dependent on the REMOTE_URL
 you are mirroring and you only need to use two new commands in
 addition to common L<git(1)> commands.
 
-	git clone --mirror REMOTE_URL /path/to/repo.git
+Instructions are different depending on whether the inbox
+is L<public-inbox-v1-format(5)> or L<public-inbox-v2-format(5)>.
+See the "Archives are clonable:" part of the WWW interface
+of a given inbox for cloning instructions specific to
+that inbox.  The instructions are roughly:
 
-	# The following should create the necessary entry in
-	# ~/.public-inbox/config
-	public-inbox-init NAME /path/to/repo.git MY_URL LIST_ADDRESS
+  # for v1 inboxes:
+  git clone --mirror URL INBOX_DIR
 
-	# Optional but strongly recommended for hosting HTTP
-	# (and required for NNTP)
-	# enable search (requires Search::Xapian and DBD::SQLite)
-	public-inbox-index /path/to/repo.git
+  # for v2 inboxes (each epoch needs to be cloned):
+  git clone --mirror URL/EPOCH INBOX_DIR/git/EPOCH.git
 
-	# Periodically update the repo with the following commands
-	# to update the git repo and index new messages:
-	cd /path/to/repo.git && git fetch && public-inbox-index
+  # The following should create the necessary entry in
+  # ~/.public-inbox/config, use "-V2" only for v2 inboxes:
+  public-inbox-init [-V2] NAME INBOX_DIR MY_URL LIST_ADDRESS
 
-See L</"Hosting public-inboxes"> below for info on how to expose
+  # Optional but strongly recommended for hosting HTTP
+  # (and required for NNTP)
+  # enable overview (requires DBD::SQLite) and, if Search::Xapian is
+  # available, search:
+  public-inbox-index INBOX_DIR
+
+  # Periodically fetch the repo using git-fetch(1)
+  # for v1 inboxes:
+  git --git-dir=INBOX_DIR fetch
+
+  # for v2 (in most cases, only the newest epoch needs to be fetched):
+  git --git-dir=INBOX_DIR/git/EPOCH.git fetch
+
+  # index new messages after fetching:
+  public-inbox-index INBOX_DIR
+
+See L</"Serving public-inboxes"> below for info on how to expose
 your mirror to other readers.
 
-=head2 Mirroring mailing lists directly
+=head2 Mirroring mailing lists
 
-Mirroring existing mailing lists may be done by any reader
+Mirroring mailing lists may be done by any reader
 of a mailing list using L<public-inbox-watch(1)>.
 
-	# This will create a new git repository:
-	public-inbox-init NAME /path/to/repo.git MY_URL LIST_ADDRESS
+	# This will create a new v2 inbox:
+	public-inbox-init -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS
 
 Then, see the L<public-inbox-watch(1)> manual for configuring
-C<watch>, C<watchheader>, and the optional C<spamcheck> and
-C<watchspam> entries.
+C<watch>, C<watchheader>, C<listid> and the optional C<spamcheck>
+and C<watchspam> entries.
 
 You will need to leave L<public-inbox-watch(1)> running to
 keep the mailbox up-to-date as messages are delivered to
@@ -69,15 +86,20 @@ is recommended.  L<public-inbox-watch(1)> will automatically
 maintain the indices if they were created by
 L<public-inbox-index(1)>
 
-	public-inbox-index /path/to/repo.git
+	public-inbox-index INBOX_DIR
+
+Instead of using L<public-inbox-watch(1)>, using
+L<public-inbox-mda(1)> with the C<--no-precheck> option and
+relying on the C<listid> directive in L<public-inbox-config(5)>
+is also an option.
 
-=head2 Hosting standalone
+=head2 Hosting standalone inboxes
 
 Using L<public-inbox-init(1)> to initialize the inbox as in the
 other methods is recommended.  See L<public-inbox-mda(1)> for
 more details; but this also requires MTA-specific knowledge.
 
-=head2 Hosting public-inboxes
+=head2 Serving public-inboxes
 
 Since public-inboxes are git repositories, they may be served to
 remote clients via L<git-daemon(1)> as well as specialized HTTP
@@ -87,8 +109,7 @@ See L<public-inbox-httpd(1)> and L<public-inbox-nntpd(1)>
 for more information on using these daemons.
 
 Hosting a public-inbox over HTTP or NNTP will never require
-write access to any files in the git repository, including
-the search indices or article number map database.
+write access to any files in the inbox directory.
 
 Users familiar with PSGI and L<Plack> may also use
 L<PublicInbox::WWW> with the preferred server instead of
@@ -98,11 +119,11 @@ L<public-inbox-httpd(1)>
 
 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
 
-Copyright 2016 all contributors L<mailto:meta@public-inbox.org>
+Copyright 2016-2021 all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>