From 41f45d038aab6e14b74d5ef0d6836cbc7eabb03b Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Wed, 16 Oct 2019 11:14:50 +0000 Subject: [PATCH] doc: update public-inbox-overview(7) for v2 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..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 commands. - git clone --mirror REMOTE_URL /path/to/repo.git +Instructions are different depending on whether the inbox +is L or L. +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 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 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. # 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 manual for configuring -C, C, and the optional C and -C entries. +C, C, C and the optional C +and C entries. You will need to leave L running to keep the mailbox up-to-date as messages are delivered to @@ -69,15 +86,20 @@ is recommended. L will automatically maintain the indices if they were created by L - public-inbox-index /path/to/repo.git + public-inbox-index INBOX_DIR + +Instead of using L, using +L with the C<--no-precheck> option and +relying on the C directive in L +is also an option. -=head2 Hosting standalone +=head2 Hosting standalone inboxes Using L to initialize the inbox as in the other methods is recommended. See L 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 as well as specialized HTTP -- 2.44.0