From 7d9ec0754afeabb9f336c5220ef415c3ea27a0b6 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 2 Nov 2021 12:54:35 -0400
Subject: [PATCH] Doc: clean up some places that mentioned template1 but not
 template0.

Improve old text that wasn't updated when we added template0 to
the standard database set.

Per suggestion from P. Luzanov.

Discussion: https://postgr.es/m/163583775122.675.3700595100340939507@wrigleys.postgresql.org
---
 doc/src/sgml/manage-ag.sgml  | 14 ++++++++++----
 doc/src/sgml/ref/initdb.sgml | 19 +++++++++++--------
 doc/src/sgml/runtime.sgml    |  8 ++++----
 3 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 74055a47065..23f116befeb 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -136,15 +136,21 @@ CREATE DATABASE <replaceable>name</replaceable>;
   </para>
 
   <para>
-   A second database,
-   <literal>template1</literal>,<indexterm><primary>template1</primary></indexterm>
-   is also created during database cluster initialization.  Whenever a
+   Two additional databases,
+   <literal>template1</literal><indexterm><primary>template1</primary></indexterm>
+   and
+   <literal>template0</literal>,<indexterm><primary>template0</primary></indexterm>
+   are also created during database cluster initialization.  Whenever a
    new database is created within the
    cluster, <literal>template1</literal> is essentially cloned.
    This means that any changes you make in <literal>template1</literal> are
    propagated to all subsequently created databases. Because of this,
    avoid creating objects in <literal>template1</literal> unless you want them
-   propagated to every newly created database.  More details
+   propagated to every newly created database.
+   <literal>template0</literal> is meant as a pristine copy of the original
+   contents of <literal>template1</literal>.  It can be cloned instead
+   of <literal>template1</literal> when it is important to make a database
+   without any such site-local additions.  More details
    appear in <xref linkend="manage-ag-templatedbs"/>.
   </para>
 
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 9d47cacbe0b..8f71c7c962d 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -46,13 +46,16 @@ PostgreSQL documentation
    Creating a database cluster consists of creating the directories in
    which the database data will live, generating the shared catalog
    tables (tables that belong to the whole cluster rather than to any
-   particular database), and creating the <literal>template1</literal>
-   and <literal>postgres</literal> databases. When you later create a
-   new database, everything in the <literal>template1</literal> database is
-   copied.  (Therefore, anything installed in <literal>template1</literal>
-   is automatically copied into each database created later.)
+   particular database), and creating the <literal>postgres</literal>,
+   <literal>template1</literal>, and <literal>template0</literal> databases.
    The <literal>postgres</literal> database is a default database meant
    for use by users, utilities and third party applications.
+   <literal>template1</literal> and <literal>template0</literal> are
+   meant as source databases to be copied by later <command>CREATE
+   DATABASE</command> commands.  <literal>template0</literal> should never
+   be modified, but you can add objects to <literal>template1</literal>,
+   which by default will be copied into databases created later.  See
+   <xref linkend="manage-ag-templatedbs"/> for more details.
   </para>
 
   <para>
@@ -88,7 +91,7 @@ PostgreSQL documentation
    collation order (<literal>LC_COLLATE</literal>) and character set classes
    (<literal>LC_CTYPE</literal>, e.g., upper, lower, digit) can be set separately
    for a database when it is created. <command>initdb</command> determines
-   those settings for the <literal>template1</literal> database, which will
+   those settings for the template databases, which will
    serve as the default for all other databases.
   </para>
 
@@ -184,9 +187,9 @@ PostgreSQL documentation
       <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
       <listitem>
        <para>
-        Selects the encoding of the template database. This will also
+        Selects the encoding of the template databases. This will also
         be the default encoding of any database you create later,
-        unless you override it there.  The default is derived from the locale, or
+        unless you override it then.  The default is derived from the locale, or
         <literal>SQL_ASCII</literal> if that does not work. The character sets supported by
         the <productname>PostgreSQL</productname> server are described
         in <xref linkend="multibyte-charset-supported"/>.
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index d74d1ed7afa..58150996b80 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -74,10 +74,10 @@
    which is meant as a default database for use by utilities, users and third
    party applications.  The database server itself does not require the
    <literal>postgres</literal> database to exist, but many external utility
-   programs assume it exists.  Another database created within each cluster
-   during initialization is called
-   <literal>template1</literal>.  As the name suggests, this will be used
-   as a template for subsequently created databases; it should not be
+   programs assume it exists.  There are two more databases created within
+   each cluster during initialization, named <literal>template1</literal>
+   and <literal>template0</literal>.  As the names suggest, these will be
+   used as templates for subsequently-created databases; they should not be
    used for actual work.  (See <xref linkend="managing-databases"/> for
    information about creating new databases within a cluster.)
   </para>