[PATCH] doc: improve wording of "inbox" vs "repository"

[PATCH] doc: improve wording of "inbox" vs "repository"

[Eric Wong]

Since v2 inboxes contain multiple git repositories, avoid the
use of the word "repository" when referring to inboxes as a
whole in most places.
---
 Documentation/public-inbox-convert.pod   | 6 +++---
 Documentation/public-inbox-daemon.pod    | 3 +--
 Documentation/public-inbox-index.pod     | 6 +++---
 Documentation/public-inbox-overview.pod  | 5 ++---
 Documentation/public-inbox-v2-format.pod | 4 ++--
 Documentation/public-inbox-watch.pod     | 2 +-
 HACKING                                  | 2 +-
 TODO                                     | 2 +-
 script/public-inbox-index                | 3 +--
 9 files changed, 15 insertions(+), 18 deletions(-)

diff --git a/Documentation/public-inbox-convert.pod b/Documentation/public-inbox-convert.pod
index fc5c4762..a8a5658c 100644
--- a/Documentation/public-inbox-convert.pod
+++ b/Documentation/public-inbox-convert.pod
@@ -20,9 +20,9 @@ once they are satisfied with the conversion.
 
 =item --no-index
 
-Disables Xapian and overview DB indexing on the new repository.
-By default, public-inbox-convert creates a new index in the v2
-repository and indexes all existing messages, a lengthy
+Disables Xapian and overview DB indexing on the new inbox.
+By default, public-inbox-convert creates a new index in the
+v2 inbox and indexes all existing messages, a lengthy
 operation for large inboxes.
 
 =item -j JOBS, --jobs=JOBS
diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod
index cb903df2..6091e8e6 100644
--- a/Documentation/public-inbox-daemon.pod
+++ b/Documentation/public-inbox-daemon.pod
@@ -12,8 +12,7 @@ public-inbox-daemon - common usage for public-inbox network daemons
 This manual describes common options and behavior for
 public-inbox network daemons.  Network daemons for public-inbox
 provide read-only NNTP and HTTP access to public-inboxes.  Write
-access to a public-inbox repository will never be required to
-run these.
+access to a public-inbox will never be required to run these.
 
 These daemons are implemented with a common core using
 non-blocking sockets and optimized for fairness; even with
diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod
index 7c04f753..14113ec8 100644
--- a/Documentation/public-inbox-index.pod
+++ b/Documentation/public-inbox-index.pod
@@ -34,8 +34,8 @@ normal search functionality.
 
 =item --reindex
 
-Forces a search engine re-index of all messages in the
-repository.  This can be used for in-place upgrades while
+Forces a re-index of all messages in the inbox.
+This can be used for in-place upgrades and bugfixes while
 NNTP/HTTP server processes are utilizing the index.  Keep in
 mind this roughly doubles the size of the already-large
 Xapian database.  Running L<public-inbox-compact(1)>
@@ -58,7 +58,7 @@ For v1 (ssoma) repositories described in L<public-inbox-v1-format>.
 All public-inbox-specific files are contained within the
 C<$GIT_DIR/public-inbox/> directory.
 
-v2 repositories are described in L<public-inbox-v2-format>.
+v2 inboxes are described in L<public-inbox-v2-format>.
 
 =head1 ENVIRONMENT
 
diff --git a/Documentation/public-inbox-overview.pod b/Documentation/public-inbox-overview.pod
index 583aea87..44989e6e 100644
--- a/Documentation/public-inbox-overview.pod
+++ b/Documentation/public-inbox-overview.pod
@@ -70,7 +70,7 @@ your mirror to other readers.
 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:
+	# This will create a new v2 inbox:
 	public-inbox-init -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS
 
 Then, see the L<public-inbox-watch(1)> manual for configuring
@@ -109,8 +109,7 @@ See L<public-inbox-httpd(1)> and L<public-inbox-nntpd(1)>
 for more information on using these daemons.
 
 Hosting a public-inbox over HTTP or NNTP will never require
-write access to any files in the git repository, including
-the search indices or article number map database.
+write access to any files in the inbox directory.
 
 Users familiar with PSGI and L<Plack> may also use
 L<PublicInbox::WWW> with the preferred server instead of
diff --git a/Documentation/public-inbox-v2-format.pod b/Documentation/public-inbox-v2-format.pod
index 730f6633..d87a717d 100644
--- a/Documentation/public-inbox-v2-format.pod
+++ b/Documentation/public-inbox-v2-format.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-public-inbox v2 repository description
+public-inbox v2 format description
 
 =head1 DESCRIPTION
 
@@ -226,7 +226,7 @@ no sense in a public archive.
 =head1 THANKS
 
 Thanks to the Linux Foundation for sponsoring the development
-and testing of the v2 repository format.
+and testing of the v2 format.
 
 =head1 COPYRIGHT
 
diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod
index 87e4da49..8a3ef076 100644
--- a/Documentation/public-inbox-watch.pod
+++ b/Documentation/public-inbox-watch.pod
@@ -37,7 +37,7 @@ In ~/.public-inbox/config:
 
 public-inbox-watch allows watching a mailbox (currently only
 Maildir) for the arrival of new messages and automatically
-importing them into a public-inbox (git) repository.
+importing them into public-inbox git repositories and indices.
 public-inbox-watch is useful in situations when a user wishes to
 mirror an existing mailing list, but has no access to run
 L<public-inbox-mda(1)> on a server.  Unlike public-inbox-mda
diff --git a/HACKING b/HACKING
index 859745ef..5e02302c 100644
--- a/HACKING
+++ b/HACKING
@@ -32,7 +32,7 @@ may be too difficult to upgrade due to resource demands.
 Only depend on Free Software packages which exist in the "main"
 section of Debian "stable" distribution.  That is Debian 9.x
 ("stretch") as of this writing, but "oldstable" (8.x, "jessie")
-remains supported for v1 repositories.
+remains supported for v1 inboxes.
 
 In general, we favor mature and well-tested old things rather than
 the shiny new.
diff --git a/TODO b/TODO
index 94f690ef..70ea8eee 100644
--- a/TODO
+++ b/TODO
@@ -17,7 +17,7 @@ all need to be considered for everything we introduce)
   https://public-inbox.org/meta/20160411034104.GA7817@dcvr.yhbt.net/
   Perhaps make this depend solely the NNTP server and work as a proxy.
   Meaning users can run this without needing a full copy of the
-  archives in a git repository.
+  archives in a git repositories.
 
 * HTTP and NNTP proxy support.  Allow us to be a frontend for
   firewalled off (or Tor-exclusive) instances.  The use case is
diff --git a/script/public-inbox-index b/script/public-inbox-index
index 2c7c4f13..c6910420 100755
--- a/script/public-inbox-index
+++ b/script/public-inbox-index
@@ -1,8 +1,7 @@
 #!/usr/bin/perl -w
 # Copyright (C) 2015-2020 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
-# Basic tool to create a Xapian search index for a git repository
-# configured for public-inbox.
+# Basic tool to create a Xapian search index for a public-inbox.
 # Usage with libeatmydata <https://www.flamingspork.com/projects/libeatmydata/>
 # highly recommended: eatmydata public-inbox-index INBOX_DIR
 

Re: [PATCH] doc: improve wording of "inbox" vs "repository"

[Kyle Meyer]

Eric Wong <e@yhbt.net> writes:

> Since v2 inboxes contain multiple git repositories, avoid the
> use of the word "repository" when referring to inboxes as a
> whole in most places.
[...]
> diff --git a/TODO b/TODO
> index 94f690ef..70ea8eee 100644
> --- a/TODO
> +++ b/TODO
> @@ -17,7 +17,7 @@ all need to be considered for everything we introduce)
>    https://public-inbox.org/meta/20160411034104.GA7817@dcvr.yhbt.net/
>    Perhaps make this depend solely the NNTP server and work as a proxy.
>    Meaning users can run this without needing a full copy of the
> -  archives in a git repository.
> +  archives in a git repositories.

I suppose it doesn't matter much in a TODO file, but you forgot to drop
an "a" here.

Oh, and public-inbox is a wonderful thing.  Thank you.

Re: [PATCH] doc: improve wording of "inbox" vs "repository"

[Eric Wong]

Kyle Meyer <kyle@kyleam.com> wrote:
> Eric Wong <e@yhbt.net> writes:
> 
> > Since v2 inboxes contain multiple git repositories, avoid the
> > use of the word "repository" when referring to inboxes as a
> > whole in most places.
> [...]
> > diff --git a/TODO b/TODO
> > index 94f690ef..70ea8eee 100644
> > --- a/TODO
> > +++ b/TODO
> > @@ -17,7 +17,7 @@ all need to be considered for everything we introduce)
> >    https://public-inbox.org/meta/20160411034104.GA7817@dcvr.yhbt.net/
> >    Perhaps make this depend solely the NNTP server and work as a proxy.
> >    Meaning users can run this without needing a full copy of the
> > -  archives in a git repository.
> > +  archives in a git repositories.
> 
> I suppose it doesn't matter much in a TODO file, but you forgot to drop
> an "a" here.

Thanks, pushed as commit d87053bf6cae0258125e84e1531d5f1206c53288

> Oh, and public-inbox is a wonderful thing.  Thank you.

You're welcome :>

[PATCH 2/1] INSTALL: s/repositories/inboxes/

[Eric Wong]

Since v2 inboxes can be made of several git repositories,
consistently call them "inboxes", instead.
---
 INSTALL | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/INSTALL b/INSTALL
index bf1c821a..7d14ca55 100644
--- a/INSTALL
+++ b/INSTALL
@@ -21,9 +21,9 @@ Requirements
 public-inbox requires a number of other packages to access its full
 functionality.  The core tools are, of course:
 
-* Git (1.8.0+, 2.6+ for writing v2 repositories)
+* Git (1.8.0+, 2.6+ for writing v2 inboxes)
 * Perl 5.10.1+
-* DBD::SQLite (needed for NNTP, message threading, and v2 repositories)
+* DBD::SQLite (needed for NNTP, message threading, and v2 inboxes)
 
 To accept incoming mail into a public inbox, you'll likely want: