Date: Mon, 11 Nov 2019 10:14:29 -0300
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Daniel Gustafsson <daniel@yesql.se>, Bruce Momjian <bruce@momjian.us>,
	brian.williams@mayalane.com, pgsql-docs@lists.postgresql.org
Subject: Re: The word "virgin" used incorrectly and probably better off
 replaced
Message-ID: <20191111131429.GA11285@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="9jxsPFA5p3P2qPhR"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <11820.1573231319@sss.pgh.pa.us>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk


--9jxsPFA5p3P2qPhR
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On 2019-Nov-08, Tom Lane wrote:

> Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> > On 2019-Nov-08, Tom Lane wrote:
> >> So the patch becomes s/virgin/pristine/g plus add a parenthetical
> >> definition for the first use?  Works for me.
> 
> > Well, there are three uses of the word "virgin".  The first is for
> > "virgin user", and the patch turns that into just "user".
> 
> Uh, no, read the next lines.  In both cases those are referring
> to "virgin user database" or "virgin database", and this patch
> is removing an important qualifier.  It needs to be s/virgin/pristine/
> in all these places.

Doh, right.

One problem with doing it that way is that the proposed parenthical
comment partly duplicates the text immediately following it, so I'm no
longer so sure that adding it is good; I think that changing "local
additions" to "local additions and changes" might be sufficient, or
maybe that is too obscure for novices?  For create_database.sgml it does
seem to make a little more sense, but I'm not 100% there either.

Maybe "changes" can become "database-local system changes"? i.e.,

    By instructing CREATE DATABASE to copy template0 instead of
    template1, you can create a pristine user database that contains
    none of the site-local additions and database-local system changes
    in template1.

... though, argh, "-local" appearing twice makes that look bad too :-(
(I'm not sure that it is clear what a "database-local system change" is.)

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--9jxsPFA5p3P2qPhR
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="v3-0001-No-more-virgins.patch"

diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 0154064e50..00ecc2d843 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -199,11 +199,11 @@ createdb -O <replaceable>rolename</replaceable> <replaceable>dbname</replaceable
    should never be changed after the database cluster has been
    initialized.  By instructing
    <command>CREATE DATABASE</command> to copy <literal>template0</literal> instead
-   of <literal>template1</literal>, you can create a <quote>virgin</quote> user
-   database that contains none of the site-local additions in
+   of <literal>template1</literal>, you can create a <quote>pristine</quote> user
+   database that contains none of the site-local additions and changes in
    <literal>template1</literal>.  This is particularly handy when restoring a
    <literal>pg_dump</literal> dump: the dump script should be restored in a
-   virgin database to ensure that one recreates the correct contents
+   pristine database to ensure that one recreates the correct contents
    of the dumped database, without conflicting with objects that
    might have been added to <literal>template1</literal> later on.
   </para>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 4014f6703b..7b48263364 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -54,8 +54,10 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
    system database <literal>template1</literal>.  A different template can be
    specified by writing <literal>TEMPLATE
    <replaceable class="parameter">name</replaceable></literal>.  In particular,
-   by writing <literal>TEMPLATE template0</literal>, you can create a virgin
-   database containing only the standard objects predefined by your
+   by writing <literal>TEMPLATE template0</literal>, you can create a
+   pristine database (one where no user-defined objects exist and where
+   system objects have not been altered)
+   containing only the standard objects predefined by your
    version of <productname>PostgreSQL</productname>.  This is useful
    if you wish to avoid copying
    any installation-local objects that might have been added to

--9jxsPFA5p3P2qPhR--