[PATCH 2/3] doc: update public-inbox-overview(7) for v2

[Eric Wong <e@80x24.org>]

The overview was v1-specific and probably confusing/misleading
to new users since v2 is favored.

Hopefully improve wording while we're at it and avoid
overloading terms like "parts" (which could be confused with
Xapian "shards").

Using the word "directly" after "Mirroring mailing lists"
did not make sense to me, either.
---
 Documentation/public-inbox-overview.pod | 68 ++++++++++++++++---------
 1 file changed, 45 insertions(+), 23 deletions(-)

diff --git a/Documentation/public-inbox-overview.pod b/Documentation/public-inbox-overview.pod
index 46060d0c..782c2f8b 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 most recent 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