From 549f74733f45804cd3180de853e5d0610eecc22f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Thu, 2 Feb 2017 14:57:46 -0500
Subject: [PATCH] doc: Update CREATE DATABASE examples

The example of using CREATE DATABASE with the ENCODING option did not
work anymore (except in special circumstances) and did not represent a
good general-purpose example, so write some new examples.

Reported-by: marc+pgsql@milestonerdl.com
---
 doc/src/sgml/ref/create_database.sgml | 30 ++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index cf0d53b301..48386a29f9 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -284,17 +284,33 @@ CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
   </para>
 
   <para>
-   To create a database <literal>music</> which supports the ISO-8859-1
-   character set:
+   To create a database <literal>music</> with a different locale:
+<programlisting>
+CREATE DATABASE music
+    LC_COLLATE 'sv_SE.utf8' LC_CTYPE 'sv_SE.utf8'
+    TEMPLATE template0;
+</programlisting>
+    In this example, the <literal>TEMPLATE template0</> clause is required if
+    the specified locale is different from the one in <literal>template1</>.
+    (If it is not, then specifying the locale explicitly is redundant.)
+  </para>
 
+  <para>
+   To create a database <literal>music2</> with a different locale and a
+   different character set encoding:
 <programlisting>
-CREATE DATABASE music ENCODING 'LATIN1' TEMPLATE template0;
+CREATE DATABASE music2
+    LC_COLLATE 'sv_SE.iso885915' LC_CTYPE 'sv_SE.iso885915'
+    ENCODING LATIN9
+    TEMPLATE template0;
 </programlisting>
+   The specified locale and encoding settings must match, or an error will be
+   reported.
+  </para>
 
-   In this example, the <literal>TEMPLATE template0</> clause would only
-   be required if <literal>template1</>'s encoding is not ISO-8859-1.
-   Note that changing encoding might require selecting new
-   <literal>LC_COLLATE</> and <literal>LC_CTYPE</> settings as well.
+  <para>
+   Note that locale names are specific to the operating system, so that the
+   above commands might not work in the same way everywhere.
   </para>
  </refsect1>
 
-- 
2.40.0