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.

6 files changed, 76 insertions, 56 deletions

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 869c4fafd99..ce4a1f81e1a 100644
--- a/doc/src/sgml/charset.sgml
+++ b/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
-    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:
+    with the locale setting of its execution environment by default,
+    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 instruct
+    <command>initdb</command> exactly which locale to use by
+    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
-    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
-    then the specifications look like this:
+    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</> (French
+    Canadian).  If more than one character set can be useful for a
+    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>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f0cda231962..769357ae5db 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 35ae8a75ade..065ee479366 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 6a5581bcab7..a6b2c8d383c 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 92a1301cee1..189a4279778 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/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
-        override it there.  The default is <literal>SQL_ASCII</literal>.
+        be the default encoding of any database you create later,
+        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>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index cf74272b9bc..0d6b6dba08f 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/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
-        enabled during compilation.  If so, the default is on.
+        detect programming mistakes.  This option is only available if
+        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
-	buffer is 8 kB.
+	processes.  The default value of this parameter is chosen
+	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
-        a list and descriptions.  Most of the other command line
-        options are in fact short forms of such a parameter
-        assignment.  <option>-c</> can appear multiple times to set
-        multiple parameters.
+        Sets a named run-time parameter. The configuration parameters
+        supported by <productname>PostgreSQL</productname> are
+        described in <xref linkend="runtime-config">. Most of the
+        other command line options are in fact short forms of such a
+        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
-        <literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
-        documentation before using this!
+        system crash.  Specifying this option is equivalent to
+        disabling the <xref linkend="guc-fsync"> configuration
+        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
-        a space-separated list of addresses, or <literal>*</> to specify
-        listening on all available interfaces.  An empty value specifies
-        not listening on any IP addresses, in which case only Unix-domain
-        sockets can be used to connect to the <command>postmaster</command>.
-        Defaults to listening only
-        on <systemitem class="systemname">localhost</systemitem>.
-        This option is equivalent to setting <literal>listen_addresses</> in
-        <filename>postgresql.conf</>.
+        connections from client applications.  The value can also be a
+        space-separated list of addresses, or <literal>*</> to specify
+        listening on all available interfaces.  An empty value
+        specifies not listening on any IP addresses, in which case
+        only Unix-domain sockets can be used to connect to the
+        <command>postmaster</command>.  Defaults to listening only on
+        <systemitem class="systemname">localhost</systemitem>.
+        Specifying this option is equivalent to setting the <xref
+        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
-        better to set <literal>listen_addresses</> directly.
+        full functionality of <xref linkend="guc-listen-addresses">.
+        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
-	enabled to use this option.
+	Enables secure connections using <acronym>SSL</acronym>.
+	<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>