Improve the locale and character set docs, add some <xref>s pointing

to the character set docs where appropriate, and improve the postmaster
reference page. Character set cross-refs suggested by Gavin Kistner.

doc/src/sgml/charset.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/charset.sgml,v 2.43 2004/03/09 16:57:46 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/charset.sgml,v 2.44 2004/03/23 02:47:35 neilc Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
@@ -52,24 +52,24 @@
     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
+    with the locale setting of its execution environment by default,
-    system is already set to use the locale that you want in your
+    so if your system is already set to use the locale that you want
-    database cluster then there is nothing else you need to do.  If
+    in your database cluster then there is nothing else you need to
-    you want to use a different locale (or you are not sure which
+    do.  If you want to use a different locale (or you are not sure
-    locale your system is set to), you can tell
+    which locale your system is set to), you can instruct
-    <command>initdb</command> exactly which locale you want with the
+    <command>initdb</command> exactly which locale to use by
-    option <option>--locale</option>.  For example:
+    specifying the <option>--locale</option> option. For example:
 <screen>
 initdb --locale=sv_SE
 </screen>
    </para>
 
    <para>
-    This example sets the locale to Swedish (<literal>sv</>) as spoken in
+    This example sets the locale to Swedish (<literal>sv</>) as spoken
-    Sweden (<literal>SE</>).  Other possibilities might be
+    in Sweden (<literal>SE</>).  Other possibilities might be
-    <literal>en_US</> (U.S. English) and <literal>fr_CA</> (Canada,
+    <literal>en_US</> (U.S. English) and <literal>fr_CA</> (French
-    French).  If more than one character set can be useful for a locale
+    Canadian).  If more than one character set can be useful for a
-    then the specifications look like this:
+    locale then the specifications look like this:
     <literal>cs_CZ.ISO8859-2</>. What locales are available under what
     names on your system depends on what was provided by the operating
     system vendor and what was installed.
@@ -141,7 +141,7 @@ initdb --locale=sv_SE
     The other locale categories can be changed as desired whenever the
     server is running 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
+    linkend="runtime-config-client-format"> 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
@@ -196,7 +196,7 @@ initdb --locale=sv_SE
     <itemizedlist>
      <listitem>
       <para>
-       Sort order in queries using <command>ORDER BY</>
+       Sort order in queries using <literal>ORDER BY</>
        <indexterm><primary>ORDER BY</><secondary>and locales</></indexterm>
       </para>
      </listitem>
@@ -286,7 +286,7 @@ initdb --locale=sv_SE
    databases each with a different character set.
   </para>
 
-   <sect2>
+   <sect2 id="multibyte-charset-supported">
     <title>Supported Character Sets</title>
 
     <para>

doc/src/sgml/datatype.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.143 2004/03/09 16:57:46 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.144 2004/03/23 02:47:35 neilc Exp $
 -->
 
  <chapter id="datatype">
@@ -945,7 +945,10 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
    <para>
     Refer to <xref linkend="sql-syntax-strings"> for information about
     the syntax of string literals, and to <xref linkend="functions">
-    for information about available operators and functions.
+    for information about available operators and functions. The
+    database character set determines the character set used to store
+    textual values; for more information on character set support,
+    refer to <xref linkend="multibyte">.
    </para>
 
    <example>

doc/src/sgml/ref/create_database.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.37 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.38 2004/03/23 02:47:35 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -139,10 +139,12 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
       <term><replaceable class="parameter">encoding</replaceable></term>
       <listitem>
        <para>
-        Character set encoding to use in the new database.  Specify
+    Character set encoding to use in the new database.  Specify
 	a string constant (e.g., <literal>'SQL_ASCII'</literal>),
 	or an integer encoding number, or <literal>DEFAULT</literal>
-	to use the default encoding.
+	to use the default encoding. The character sets supported by the
+	<productname>PostgreSQL</productname> server are described in
+	<xref linkend="multibyte-charset-supported">.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/createdb.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createdb.sgml,v 1.37 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createdb.sgml,v 1.38 2004/03/23 02:47:35 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -112,7 +112,10 @@ PostgreSQL documentation
       <term><option>--encoding <replaceable class="parameter">encoding</replaceable></></term>
       <listitem>
        <para>
-        Specifies the character encoding scheme to be used in this database.
+        Specifies the character encoding scheme to be used in this
+        database. The character sets supported by the
+        <productname>PostgreSQL</productname> server are described in
+        <xref linkend="multibyte-charset-supported">.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/initdb.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.28 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.29 2004/03/23 02:47:35 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -120,8 +120,11 @@ PostgreSQL documentation
       <listitem>
        <para>
         Selects the encoding of the template database. This will also
-        be the default encoding of any database you create later, unless you
+        be the default encoding of any database you create later,
-        override it there.  The default is <literal>SQL_ASCII</literal>.
+        unless you override it there.  The default is
+        <literal>SQL_ASCII</literal>. The character sets supported by
+        the <productname>PostgreSQL</productname> server are described
+        in <xref linkend="multibyte-charset-supported">.
        </para>
       </listitem>
      </varlistentry>
@@ -132,7 +135,8 @@ PostgreSQL documentation
        <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.
+        environment that <command>initdb</command> runs in. Locale
+        support is described in <xref linkend="locale">.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/postmaster.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.47 2004/03/23 01:23:48 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.48 2004/03/23 02:47:35 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -93,8 +93,9 @@ PostgreSQL documentation
       <listitem>
        <para>
         Enables run-time assertion checks, which is a debugging aid to
-        detect programming mistakes.  This is only available if it was
+        detect programming mistakes.  This option is only available if
-        enabled during compilation.  If so, the default is on.
+        assertions were enabled when <productname>PostgreSQL</> was
+        compiled. If so, the default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -104,8 +105,9 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Sets the number of shared buffers for use by the server
-	processes.  This value defaults to 64 buffers, where each
+	processes.  The default value of this parameter is chosen
-	buffer is 8 kB.
+	automatically by <application>initdb</application>; refer to <xref
+	linkend="runtime-config-resource-memory"> for more information.
        </para>
       </listitem>
      </varlistentry>
@@ -114,11 +116,12 @@ PostgreSQL documentation
       <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
       <listitem>
        <para>
-        Sets a named run-time parameter. Consult <xref linkend="runtime-config"> for
+        Sets a named run-time parameter. The configuration parameters
-        a list and descriptions.  Most of the other command line
+        supported by <productname>PostgreSQL</productname> are
-        options are in fact short forms of such a parameter
+        described in <xref linkend="runtime-config">. Most of the
-        assignment.  <option>-c</> can appear multiple times to set
+        other command line options are in fact short forms of such a
-        multiple parameters.
+        parameter assignment.  <option>-c</> can appear multiple times
+        to set multiple parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -129,7 +132,7 @@ PostgreSQL documentation
        <para>
         Sets the debug level.  The higher this value is set, the more
         debugging output is written to the server log.  Values are from
-	1 to 5.
+        1 to 5.
        </para>
       </listitem>
      </varlistentry>
@@ -150,10 +153,11 @@ PostgreSQL documentation
        <para>
         Disables <function>fsync</function> calls for performance
         improvement, at the risk of data corruption in event of a
-        system crash.  This option corresponds to setting
+        system crash.  Specifying this option is equivalent to
-        <literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
+        disabling the <xref linkend="guc-fsync"> configuration
-        documentation before using this!
+        parameter. Read the detailed documentation before using this!
        </para>
+
        <para>
         <option>--fsync=true</option> has the opposite effect
         of this option.
@@ -167,15 +171,15 @@ PostgreSQL documentation
        <para>
         Specifies the IP host name or address on which the
         <command>postmaster</command> is to listen for TCP/IP
-        connections from client applications.  The value can also be
+        connections from client applications.  The value can also be a
-        a space-separated list of addresses, or <literal>*</> to specify
+        space-separated list of addresses, or <literal>*</> to specify
-        listening on all available interfaces.  An empty value specifies
+        listening on all available interfaces.  An empty value
-        not listening on any IP addresses, in which case only Unix-domain
+        specifies not listening on any IP addresses, in which case
-        sockets can be used to connect to the <command>postmaster</command>.
+        only Unix-domain sockets can be used to connect to the
-        Defaults to listening only
+        <command>postmaster</command>.  Defaults to listening only on
-        on <systemitem class="systemname">localhost</systemitem>.
+        <systemitem class="systemname">localhost</systemitem>.
-        This option is equivalent to setting <literal>listen_addresses</> in
+        Specifying this option is equivalent to setting the <xref
-        <filename>postgresql.conf</>.
+        linkend="guc-listen-addresses">.
        </para>
       </listitem>
      </varlistentry>
@@ -187,13 +191,13 @@ PostgreSQL documentation
         Allows remote clients to connect via TCP/IP (Internet domain)
         connections.  Without this option, only local connections are
         accepted.  This option is equivalent to setting
-        <literal>listen_addresses</> to <literal>*</> in
+        <varname>listen_addresses</> to <literal>*</> in
         <filename>postgresql.conf</> or via <option>-h</>.
        </para>
        <para>
         This option is deprecated since it does not allow access to the
-        full functionality of <literal>listen_addresses</>.  It's usually
+        full functionality of <xref linkend="guc-listen-addresses">.
-        better to set <literal>listen_addresses</> directly.
+        It's usually better to set <varname>listen_addresses</> directly.
        </para>
       </listitem>
      </varlistentry>
@@ -214,8 +218,11 @@ PostgreSQL documentation
       <term><option>-l</option></term>
       <listitem>
        <para>
-	Enables secure connections using SSL.  You must have compiled with SSL
+	Enables secure connections using <acronym>SSL</acronym>.
-	enabled to use this option.
+	<productname>PostgreSQL</productname> must have been compiled with
+	support for <acronym>SSL</acronym> for this option to be
+	available. For more information on using <acronym>SSL</acronym>,
+	refer to <xref linkend="ssl-tcp">.
        </para>
       </listitem>
      </varlistentry>
@@ -231,7 +238,8 @@ PostgreSQL documentation
 	<option>-B</option> is required to be at least twice
 	<option>-N</option>.  See <xref linkend="kernel-resources"> for a discussion of
 	system resource requirements for large numbers of client
-	connections.)
+	connections.) Specifying this option is equivalent to setting the
+	<xref linkend="guc-max-connections"> configuration parameter.
        </para>
       </listitem>
      </varlistentry>