* [PATCH 2/3] doc: update public-inbox-overview(7) for v2
2019-10-16 11:14 [PATCH 0/3] another round of doc updates Eric Wong
2019-10-16 11:14 ` [PATCH 1/3] doc: check-man: use COLUMNS env for width Eric Wong
@ 2019-10-16 11:14 ` Eric Wong
2019-10-17 7:42 ` Eric Wong
2019-10-16 11:14 ` [PATCH 3/3] doc: avoid [<directory>] arg for git-clone(1) Eric Wong
2 siblings, 1 reply; 5+ messages in thread
From: Eric Wong @ 2019-10-16 11:14 UTC (permalink / raw)
To: meta
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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 3/3] doc: avoid [<directory>] arg for git-clone(1)
2019-10-16 11:14 [PATCH 0/3] another round of doc updates Eric Wong
2019-10-16 11:14 ` [PATCH 1/3] doc: check-man: use COLUMNS env for width Eric Wong
2019-10-16 11:14 ` [PATCH 2/3] doc: update public-inbox-overview(7) for v2 Eric Wong
@ 2019-10-16 11:14 ` Eric Wong
2 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2019-10-16 11:14 UTC (permalink / raw)
To: meta
While it is possible to host source code from the root of a URL
using git-http-backend(1), the lack of pathname in the URL can
also be confusing to users. So just add the path name of the
project into the URL itself so users can invoke "git clone"
with one command-line argument instead of two.
Of course, previously documented URLs continue to work as normal.
---
AUTHORS | 2 +-
Documentation/dc-dlvr-spam-flow.txt | 2 +-
README | 4 ++--
lib/PublicInbox/WwwStream.pm | 5 ++---
4 files changed, 6 insertions(+), 7 deletions(-)
diff --git a/AUTHORS b/AUTHORS
index 1ad02cd8..46ca20cc 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,6 +1,6 @@
This list only includes major contributors.
-See history in git (via `git clone https://public-inbox.org/public-inbox')
+See history in git (via `git clone https://public-inbox.org/public-inbox.git')
for a full history of the project.
* Eric Wong <e@80x24.org> (BDFL)
diff --git a/Documentation/dc-dlvr-spam-flow.txt b/Documentation/dc-dlvr-spam-flow.txt
index 81aba766..d151d272 100644
--- a/Documentation/dc-dlvr-spam-flow.txt
+++ b/Documentation/dc-dlvr-spam-flow.txt
@@ -45,4 +45,4 @@ delivery path as well as removing the message from the git tree.
* spamc / spamd - SpamAssassin: http://spamassassin.apache.org/
* report-spam / dc-dlvr - distributed with public-inbox in the scripts/
- directory: git clone https://public-inbox.org/ public-inbox
+ directory: git clone https://public-inbox.org/public-inbox.git
diff --git a/README b/README
index ffd433d8..f62a7e40 100644
--- a/README
+++ b/README
@@ -91,8 +91,8 @@ Hacking
AGPL source code is available via git:
- git clone https://public-inbox.org/ public-inbox
- git clone git://repo.or.cz/public-inbox
+ git clone https://public-inbox.org/public-inbox.git
+ git clone https://repo.or.cz/public-inbox.git
torsocks git clone http://hjrcffqmbrq6wope.onion/public-inbox
See below for contact info.
diff --git a/lib/PublicInbox/WwwStream.pm b/lib/PublicInbox/WwwStream.pm
index f5338c39..06c8f7d2 100644
--- a/lib/PublicInbox/WwwStream.pm
+++ b/lib/PublicInbox/WwwStream.pm
@@ -11,8 +11,7 @@ use strict;
use warnings;
use PublicInbox::Hval qw(ascii_html);
our $TOR_URL = 'https://www.torproject.org/';
-our $CODE_URL = 'https://public-inbox.org/';
-our $PROJECT = 'public-inbox';
+our $CODE_URL = 'https://public-inbox.org/public-inbox.git';
# noop for HTTP.pm (and any other PSGI servers)
sub close {}
@@ -80,7 +79,7 @@ sub _html_top ($) {
sub code_footer ($) {
my ($env) = @_;
my $u = PublicInbox::Hval::prurl($env, $CODE_URL);
- qq(AGPL code for this site: git clone <a\nhref="$u">$u</a> $PROJECT)
+ qq(AGPL code for this site: git clone <a\nhref="$u">$u</a>)
}
sub _html_end {
^ permalink raw reply related [flat|nested] 5+ messages in thread