Locale support is on by default. The choice of locale is done in initdb

and/or with GUC variables.

6 files changed, 219 insertions, 90 deletions

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 29cc7e528ef..a19940ce9a6 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.23 2002/03/22 19:20:05 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.24 2002/04/03 05:39:27 petere Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
@@ -63,35 +63,24 @@
   <sect2>
    <title>Overview</>
 
-  <para>
-    Locale support is not built into <productname>PostgreSQL</> by
-    default; to enable it, supply the <option>--enable-locale</> option
-    to the <filename>configure</> script:
-<informalexample>
+   <para>
+    Locale support is automatically initialized when a database
+    cluster is created using <command>initdb</command>.
+    <command>initdb</command> will initialize the database cluster
+    with the locale setting of its execution environment; so if your
+    system is already set to use the locale that you want in your
+    database cluster then there is nothing else you need to do.  If
+    you want to use a different locale (or you are not sure which
+    locale your system is set to), you can tell
+    <command>initdb</command> exactly which locale you want with the
+    option <option>--locale</option>.  For example:
 <screen>
-<prompt>$ </><userinput>./configure --enable-locale</>
+<prompt>$ </><userinput>initdb --locale=sv_SE</>
 </screen>
-</informalexample>
-    Locale support only affects the server; all clients are compatible
-    with servers with or without locale support.
-   </para>
-
-   <para>
-    To enable messages translated to the user's preferred language,
-    the <option>--enable-nls</option> option must be used.  This
-    option is independent of the other locale support.
    </para>
 
    <para>
-    The information about which particular cultural rules to use is
-    determined by standard environment variables.  If you are getting
-    localized behavior from other programs you probably have them set
-    up already.  The simplest way to set the localization information
-    is the <envar>LANG</> variable, for example:
-<programlisting>
-export LANG=sv_SE
-</programlisting>
-    This sets the locale to Swedish (<literal>sv</>) as spoken in
+    This example sets the locale to Swedish (<literal>sv</>) as spoken in
     Sweden (<literal>SE</>).  Other possibilities might be
     <literal>en_US</> (U.S. English) and <literal>fr_CA</> (Canada,
     French).  If more than one character set can be useful for a locale
@@ -103,9 +92,9 @@ export LANG=sv_SE
 
    <para>
     Occasionally it is useful to mix rules from several locales, e.g.,
-    use U.S. collation rules but Spanish messages.  To do that a set of
-    environment variables exist that override the default of
-    <envar>LANG</> for a particular category:
+    use U.S. collation rules but Spanish messages.  To support that, a
+    set of locale subcategories exist that control only a certain
+    aspect of the localization rules.
 
     <informaltable>
      <tgroup cols="2">
@@ -138,49 +127,79 @@ export LANG=sv_SE
      </tgroup>
     </informaltable>
 
-    Additionally, all of these specific variables and the
-    <envar>LANG</> variable can be overridden with the
-    <envar>LC_ALL</> environment variable.
+    The category names translate into names of
+    <command>initdb</command> options to override the locale choice
+    for a specific category.  For instance, to set the locale to
+    French Canadian, but use U.S. rules for formatting currency, use
+    <literal>initdb --locale=fr_CA --lc-monetary=en_US</literal>.
    </para>
 
-   <note>
-    <para>
-     Some message localization libraries also look at the environment
-     variable <envar>LANGUAGE</envar> which overrides all other locale
-     settings for the purpose of setting the language of messages.  If
-     in doubt, please refer to the documentation of your operating
-     system, in particular the
-     <citerefentry><refentrytitle>gettext</><manvolnum>3</></> manual
-     page, for more information.
-    </para>
-   </note>
-
    <para>
     If you want the system to behave as if it had no locale support,
-    use the special locale <literal>C</> or <literal>POSIX</>, or
-    simply unset all locale-related variables.
+    use the special locale <literal>C</> or <literal>POSIX</>.
+   </para>
+
+   <para>
+    The nature of some locale categories is that their value has to be
+    fixed for the lifetime of a database cluster.  That is, once
+    <command>initdb</command> has run, you cannot change them anymore.
+    <literal>LC_COLLATE</literal> and <literal>LC_CTYPE</literal> are
+    those categories.  They affect the sort order of indexes, so they
+    must be kept fixed, or indexes on text columns will become corrupt.
+    <productname>PostgreSQL</productname> enforces this by recording
+    the values of <envar>LC_COLLATE</> and <envar>LC_CTYPE</> that are
+    seen by <command>initdb</>.  The server automatically adopts
+    those two values when it is started.
+   </para>
+
+   <para>
+    The other locale categories can be changed as desired whenever the
+    server is started by setting the run-time configuration variables
+    that have the same name as the locale categories (see <xref
+    linkend="runtime-config"> for details).  The defaults that are
+    chosen by <command>initdb</command> are actually only written into
+    the configuration file <filename>postgresql.conf</filename> to
+    serve as defaults when the server is started.  If you delete the
+    assignments from <filename>postgresql.conf</filename> then the
+    server will inherit the settings from the execution environment.
    </para>
 
    <para>
     Note that the locale behavior of the server is determined by the
     environment variables seen by the server, not by the environment
-    of any client.  Therefore, be careful to set these variables
+    of any client.  Therefore, be careful to configure the correct locale settings
     before starting the server.  A consequence of this is that if
     client and server are set up to different locales, messages may
     appear in different languages depending on where they originated.
    </para>
 
+   <note>
+    <para>
+     When we speak of inheriting the locale from the execution
+     environment, this means the following on most operating systems:
+     For a given locale category, say the collation, the following
+     environment variables are consulted in this order until one is
+     found to be set: <envar>LC_ALL</envar>, <envar>LC_COLLATE</envar>
+     (the variable corresponding to the respective category),
+     <envar>LANG</envar>.  If none of these environment variables are
+     set then the locale defaults to <literal>C</literal>.
+    </para>
+
+    <para>
+     Some message localization libraries also look at the environment
+     variable <envar>LANGUAGE</envar> which overrides all other locale
+     settings for the purpose of setting the language of messages.  If
+     in doubt, please refer to the documentation of your operating
+     system, in particular the
+     <citerefentry><refentrytitle>gettext</><manvolnum>3</></> manual
+     page, for more information.
+    </para>
+   </note>
+
    <para>
-    The <envar>LC_COLLATE</> and <envar>LC_CTYPE</> variables affect the
-    sort order of indexes.  Therefore, these values must be kept fixed
-    for any particular database cluster, or indexes on text columns will
-    become corrupt.  <productname>PostgreSQL</productname> enforces this
-    by recording the values of <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
-    that are seen by <application>initdb</>.  The server automatically adopts
-    those two values when it is started; only the other <envar>LC_</>
-    categories can be set from the environment at server start-up.
-    In short, only one collation order can be used in a database cluster,
-    and it is chosen at <application>initdb</> time.
+    To enable messages translated to the user's preferred language,
+    the <option>--enable-nls</option> option must be used.  This
+    option is independent of the other locale support.
    </para>
   </sect2>
 
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index a792d52e424..1dbf460cf4c 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.86 2002/03/22 19:20:07 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.87 2002/04/03 05:39:27 petere Exp $
 -->
 
  <chapter id="datatype">
@@ -724,11 +724,9 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceabl
    </note>
 
    <para>
-    The <type>money</type> type stores U.S.-style currency with fixed
-    decimal point representation.  If
-    <productname>PostgreSQL</productname> is compiled with locale
-    support then the <type>money</type> type uses locale-specific
-    output formatting.
+    The <type>money</type> type stores a currency amount with fixed
+    decimal point representation.  The output format is
+    locale-specific.
    </para>
 
    <para>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index c8aa0dd0c95..e5f9de741af 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.74 2002/01/20 05:45:18 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.75 2002/04/03 05:39:28 petere Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -532,17 +532,6 @@ su - postgres
       </varlistentry>
 
       <varlistentry>
-       <term><option>--enable-locale</option></term>
-       <listitem>
-        <para>
-         Enables locale support. There is a performance penalty
-         associated with locale support, but if you are not in an
-         English-speaking environment you will most likely need this.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
        <term><option>--enable-recode</option></term>
        <listitem>
         <para>
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 3bbe44aeee8..8ac524e3dc8 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.19 2001/12/08 03:24:37 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.20 2002/04/03 05:39:29 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -38,6 +38,13 @@ PostgreSQL documentation
      <arg>-E </arg>
      <replaceable>encoding</replaceable>
     </group>
+    <arg>--locale <replaceable>locale</replaceable></arg>
+    <arg>--lc-collate <replaceable>locale</replaceable></arg>
+    <arg>--lc-ctype <replaceable>locale</replaceable></arg>
+    <arg>--lc-messages <replaceable>locale</replaceable></arg>
+    <arg>--lc-monetary <replaceable>locale</replaceable></arg>
+    <arg>--lc-numeric <replaceable>locale</replaceable></arg>
+    <arg>--lc-time <replaceable>locale</replaceable></arg>
     <arg>-L <replaceable>directory</replaceable></arg>
     <group><arg>--noclean</arg><arg>-n</arg></group>
     <group><arg>--debug</arg><arg>-d</arg></group>
@@ -67,6 +74,25 @@ PostgreSQL documentation
   </para>
 
   <para>
+   <command>initdb</command> initializes the database cluster's
+   default locale and character set encoding.  Some locale categories
+   are fixed for the lifetime of the cluster, so it is important to
+   make the right choice when running <command>initdb</command>.
+   Other locale categories can be changed later when the server is
+   started.  <command>initdb</command> will write those locale
+   settings into the <filename>postgresql.conf</filename>
+   configuration file so they are the default, but they can be changed
+   by editing that file.  To set the locale that
+   <command>initdb</command> uses, see the description of the
+   <option>--locale</option> option.  The character set encoding can
+   be set separately for each database as it is created.
+   <command>initdb</command> determines the encoding for the
+   <literal>template1</literal> database, which will serve as the
+   default for all other databases.  To alter the default encoding use
+   the <option>--encoding</option> option.
+  </para>
+
+  <para>
    <command>initdb</command> must be run as the user that will own the
    server process, because the server needs to have access to the
    files and directories that <command>initdb</command> creates.
@@ -150,6 +176,32 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term>--locale=<replaceable>locale</replaceable></term>
+      <listitem>
+       <para>
+        Sets the default locale for the database cluster.  If this
+        option is not specified, the locale is inherited from the
+        environment that <command>initdb</command> runs in.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>--lc-collate=<replaceable>locale</replaceable></term>
+      <term>--lc-ctype=<replaceable>locale</replaceable></term>
+      <term>--lc-messages=<replaceable>locale</replaceable></term>
+      <term>--lc-monetary=<replaceable>locale</replaceable></term>
+      <term>--lc-numeric=<replaceable>locale</replaceable></term>
+      <term>--lc-time=<replaceable>locale</replaceable></term>
+
+      <listitem>
+       <para>
+        Like <option>--locale</option>, but only sets the locale in
+        the specified category.
+       </para>
+      </listitem>
+     </varlistentry>
    </variablelist>
    </para>
 
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index c3e52dd948b..dfb96e4ff8e 100644
--- a/doc/src/sgml/release.sgml
+++ b/doc/src/sgml/release.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.129 2002/04/01 04:35:37 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.130 2002/04/03 05:39:28 petere Exp $
 -->
 
 <appendix id="release">
@@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without
 worries about funny characters.
 -->
 <literallayout><![CDATA[
+Locale support is now built by default; choice of locale is set by initdb and/or at run-time
 ALTER TABLE ALTER COLUMN SET/DROP NOT NULL
 EXPLAIN output comes out as a query result, not a NOTICE message
 DOMAINs (types that are constrained versions of base types)
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 43b6931fe18..2b0a4ad6349 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.111 2002/04/01 03:34:24 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.112 2002/04/03 05:39:29 petere Exp $
 -->
 
 <Chapter Id="runtime">
@@ -135,8 +135,14 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
   </para>
 
   <para>
+   <indexterm><primary>locale</></>
    <indexterm><primary>LC_COLLATE</></>
-   One surprise you might encounter while running
+   <command>initdb</command> also initializes the default locale for
+   the database cluster.  Normally, it will just take the locale
+   settings in the environment and apply them to the initialized
+   database.  It is possible to specify a different locale for the
+   database; more information about that can be found in <xref
+   linkend="locale">.  One surprise you might encounter while running
    <command>initdb</command> is a notice similar to this:
 <screen>
 WARNING:  Initializing database with en_US collation order.
@@ -145,18 +151,17 @@ WARNING:  Initializing database with en_US collation order.
         such queries, you may wish to set LC_COLLATE to "C" and
         re-initdb.  For more information see the Administrator's Guide.
 </screen>
-   This is intended to warn you that the currently selected locale will
-   cause indexes to be sorted in an order that prevents them from being
-   used for LIKE and regular-expression searches. If you need good
-   performance in such searches, you should set your current locale to
-   <literal>C</> and re-run <command>initdb</command>. On most systems,
-   setting the current locale is done by changing the value of the
-   environment variable <literal>LC_ALL</literal> or
-   <literal>LANG</literal>. The sort order used within a particular
-   database cluster is set by <command>initdb</command> and cannot be
-   changed later, short of dumping all data, rerunning
-   <command>initdb</command>, and reloading the data. So it's important
-   to make this choice correctly the first time.
+   This is intended to warn you that the currently selected locale
+   will cause indexes to be sorted in an order that prevents them from
+   being used for LIKE and regular-expression searches. If you need
+   good performance in such searches, you should set your current
+   locale to <literal>C</> and re-run <command>initdb</command>, e.g.,
+   by running <literal>initdb --lc-collate=C</literal>. The sort
+   order used within a particular database cluster is set by
+   <command>initdb</command> and cannot be changed later, short of
+   dumping all data, rerunning <command>initdb</command>, and
+   reloading the data. So it's important to make this choice correctly
+   the first time.
   </para>
  </sect1>
 
@@ -1317,6 +1322,71 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
      </varlistentry>
 
      <varlistentry>
+      <term><varname>LC_MESSAGES</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Sets the language in which messages are displayed.  Acceptable
+        values are system-dependent; see <xref linkend="locale"> for
+        more information.  If this variable is set to the empty string
+        (which is the default) then the value is inherited from the
+        execution environment of the server in a system-dependent way.
+       </para>
+
+       <para>
+        On some systems, this locale category does not exist.  Setting
+        this variable will still work, but there will be no effect.
+        Also, there is a chance that no translated messages for the
+        desired language exist.  In that case you will continue to see
+        the English messages.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><varname>LC_MONETARY</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Sets the locale to use for formatting monetary amounts.
+        Acceptable values are system-dependent; see <xref
+        linkend="locale"> for more information.  If this variable is
+        set to the empty string (which is the default) then the value
+        is inherited from the execution environment of the server in a
+        system-dependent way.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><varname>LC_NUMERIC</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Sets the locale to use for formatting numbers, for example
+        with the <function>to_char()</function> family of
+        functions. Acceptable values are system-dependent; see <xref
+        linkend="locale"> for more information.  If this variable is
+        set to the empty string (which is the default) then the value
+        is inherited from the execution environment of the server in a
+        system-dependent way.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><varname>LC_TIME</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Sets the locale to use for formatting date and time values,
+        for example with the <function>to_char()</function> family of
+        functions. Acceptable values are system-dependent; see <xref
+        linkend="locale"> for more information.  If this variable is
+        set to the empty string (which is the default) then the value
+        is inherited from the execution environment of the server in a
+        system-dependent way.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><varname>MAX_CONNECTIONS</varname> (<type>integer</type>)</term>
       <listitem>
        <para>