[PATCH 0/3] another round of doc updates...

[PATCH 0/3] another round of doc updates...

[Eric Wong]

Waddling towards being less confusing to newbies
(I hope...)

Eric Wong (3):
  doc: check-man: use COLUMNS env for width
  doc: update public-inbox-overview(7) for v2
  doc: avoid [<directory>] arg for git-clone(1)

 AUTHORS                                 |  2 +-
 Documentation/dc-dlvr-spam-flow.txt     |  2 +-
 Documentation/include.mk                |  2 +-
 Documentation/public-inbox-overview.pod | 68 ++++++++++++++++---------
 README                                  |  4 +-
 lib/PublicInbox/WwwStream.pm            |  5 +-
 6 files changed, 52 insertions(+), 31 deletions(-)

[PATCH 1/3] doc: check-man: use COLUMNS env for width

[Eric Wong]

That's the environment documented in ncurses(3) and man(1) from
the man-db.nongnu.org distribution of man.
---
 Documentation/include.mk | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/include.mk b/Documentation/include.mk
index 2878422c..07b9f2a3 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -92,7 +92,7 @@ doc_install :: install-man
 # n.b. not sure if our usage of man(1) is portable or not, so not
 # enabled by default "check" target:
 # check :: check-man
-check_man = @echo CHECK80 $<;COLS=80 $(MAN) ./$^ | \
+check_man = @echo CHECK80 $<;COLUMNS=80 $(MAN) ./$^ | \
 	$(AWK) '{gsub(/\b./,"")}length>80{print;err=1}END{exit(err)}' >&2
 
 %.1.cols : %.1; $(check_man)

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

[Eric Wong]

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

[PATCH 3/3] doc: avoid [<directory>] arg for git-clone(1)

[Eric Wong]

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 {

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

[Eric Wong]

Eric Wong <e@80x24.org> wrote:
> 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

> +  # for v2, in most cases, only the most recent epoch needs to be fetched:
> +  git --git-dir=INBOX_DIR/git/EPOCH.git fetch

That was >80 columns and breaks "check-man"
(that target needs to run by default, at least on gmake)

diff --git a/Documentation/public-inbox-overview.pod b/Documentation/public-inbox-overview.pod
index 782c2f8..91d4a88 100644
--- a/Documentation/public-inbox-overview.pod
+++ b/Documentation/public-inbox-overview.pod
@@ -56,7 +56,7 @@ that inbox.  The instructions are roughly:
   # for v1 inboxes:
   git --git-dir=INBOX_DIR fetch
 
-  # for v2, in most cases, only the most recent epoch needs to be fetched:
+  # 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: