X-Git-Url: http://www.git.stargrave.org/?p=public-inbox.git;a=blobdiff_plain;f=Documentation%2Fpublic-inbox-overview.pod;h=91d4a88e2eab8a0f98da9cb65f13183a724aa918;hp=46060d0cfe1f714652f5864462f4b14443cc0344;hb=41f45d038aab6e14b74d5ef0d6836cbc7eabb03b;hpb=f8cc21f0064a34042d149f31097336919adf70d1

diff --git a/Documentation/public-inbox-overview.pod b/Documentation/public-inbox-overview.pod
index 46060d0c..91d4a88e 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
+	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