charset / postmaster doc improv - Mailing list pgsql-patches

I've applied the attached patch to CVS HEAD. It improves the
postmaster reference page, the locale / character set docs, adds some
more cross-references to the locale / character set docs, and makes a
few minor fixes elsewhere. Any suggestions for future improvement are
welcome.

-Neil
Index: doc/src/sgml/charset.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/charset.sgml,v
retrieving revision 2.43
diff -c -r2.43 charset.sgml
*** a/doc/src/sgml/charset.sgml    9 Mar 2004 16:57:46 -0000    2.43
--- b/doc/src/sgml/charset.sgml    23 Mar 2004 02:15:44 -0000
***************
*** 52,75 ****
      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>
  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:
      <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.
--- 52,75 ----
      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 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</> (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,147 ****
      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
      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
--- 141,147 ----
      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-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,202 ****
      <itemizedlist>
       <listitem>
        <para>
!        Sort order in queries using <command>ORDER BY</>
         <indexterm><primary>ORDER BY</><secondary>and locales</></indexterm>
        </para>
       </listitem>
--- 196,202 ----
      <itemizedlist>
       <listitem>
        <para>
!        Sort order in queries using <literal>ORDER BY</>
         <indexterm><primary>ORDER BY</><secondary>and locales</></indexterm>
        </para>
       </listitem>
***************
*** 286,292 ****
     databases each with a different character set.
    </para>

!    <sect2>
      <title>Supported Character Sets</title>

      <para>
--- 286,292 ----
     databases each with a different character set.
    </para>

!    <sect2 id="multibyte-charset-supported">
      <title>Supported Character Sets</title>

      <para>
Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/datatype.sgml,v
retrieving revision 1.143
diff -c -r1.143 datatype.sgml
*** a/doc/src/sgml/datatype.sgml    9 Mar 2004 16:57:46 -0000    1.143
--- b/doc/src/sgml/datatype.sgml    23 Mar 2004 02:15:44 -0000
***************
*** 945,951 ****
     <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.
     </para>

     <example>
--- 945,954 ----
     <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. 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>
Index: doc/src/sgml/ref/create_database.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/create_database.sgml,v
retrieving revision 1.37
diff -c -r1.37 create_database.sgml
*** a/doc/src/sgml/ref/create_database.sgml    29 Nov 2003 19:51:38 -0000    1.37
--- b/doc/src/sgml/ref/create_database.sgml    23 Mar 2004 02:15:44 -0000
***************
*** 139,148 ****
        <term><replaceable class="parameter">encoding</replaceable></term>
        <listitem>
         <para>
!         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.
         </para>
        </listitem>
       </varlistentry>
--- 139,150 ----
        <term><replaceable class="parameter">encoding</replaceable></term>
        <listitem>
         <para>
!     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. The character sets supported by the
!     <productname>PostgreSQL</productname> server are described in
!     <xref linkend="multibyte-charset-supported">.
         </para>
        </listitem>
       </varlistentry>
Index: doc/src/sgml/ref/createdb.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/createdb.sgml,v
retrieving revision 1.37
diff -c -r1.37 createdb.sgml
*** a/doc/src/sgml/ref/createdb.sgml    29 Nov 2003 19:51:38 -0000    1.37
--- b/doc/src/sgml/ref/createdb.sgml    23 Mar 2004 02:15:44 -0000
***************
*** 112,118 ****
        <term><option>--encoding <replaceable class="parameter">encoding</replaceable></></term>
        <listitem>
         <para>
!         Specifies the character encoding scheme to be used in this database.
         </para>
        </listitem>
       </varlistentry>
--- 112,121 ----
        <term><option>--encoding <replaceable class="parameter">encoding</replaceable></></term>
        <listitem>
         <para>
!         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>
Index: doc/src/sgml/ref/initdb.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/initdb.sgml,v
retrieving revision 1.28
diff -c -r1.28 initdb.sgml
*** a/doc/src/sgml/ref/initdb.sgml    29 Nov 2003 19:51:39 -0000    1.28
--- b/doc/src/sgml/ref/initdb.sgml    23 Mar 2004 02:15:44 -0000
***************
*** 120,127 ****
        <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>.
         </para>
        </listitem>
       </varlistentry>
--- 120,130 ----
        <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>. The character sets supported by
!         the <productname>PostgreSQL</productname> server are described
!         in <xref linkend="multibyte-charset-supported">.
         </para>
        </listitem>
       </varlistentry>
***************
*** 132,138 ****
         <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>
--- 135,142 ----
         <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. Locale
!         support is described in <xref linkend="locale">.
         </para>
        </listitem>
       </varlistentry>
Index: doc/src/sgml/ref/postmaster.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/postmaster.sgml,v
retrieving revision 1.47
diff -c -r1.47 postmaster.sgml
*** a/doc/src/sgml/ref/postmaster.sgml    23 Mar 2004 01:23:48 -0000    1.47
--- b/doc/src/sgml/ref/postmaster.sgml    23 Mar 2004 02:33:37 -0000
***************
*** 93,100 ****
        <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.
         </para>
        </listitem>
       </varlistentry>
--- 93,101 ----
        <listitem>
         <para>
          Enables run-time assertion checks, which is a debugging aid to
!         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,111 ****
        <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.
         </para>
        </listitem>
       </varlistentry>
--- 105,113 ----
        <listitem>
         <para>
      Sets the number of shared buffers for use by the server
!     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,124 ****
        <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.
         </para>
        </listitem>
       </varlistentry>
--- 116,127 ----
        <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
        <listitem>
         <para>
!         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,135 ****
         <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.
         </para>
        </listitem>
       </varlistentry>
--- 132,138 ----
         <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.
         </para>
        </listitem>
       </varlistentry>
***************
*** 150,159 ****
         <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!
         </para>
         <para>
          <option>--fsync=true</option> has the opposite effect
          of this option.
--- 153,163 ----
         <para>
          Disables <function>fsync</function> calls for performance
          improvement, at the risk of data corruption in event of a
!         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,181 ****
         <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</>.
         </para>
        </listitem>
       </varlistentry>
--- 171,185 ----
         <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>.
!         Specifying this option is equivalent to setting the <xref
!         linkend="guc-listen-addresses">.
         </para>
        </listitem>
       </varlistentry>
***************
*** 187,199 ****
          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
          <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.
         </para>
        </listitem>
       </varlistentry>
--- 191,203 ----
          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
!         <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 <xref linkend="guc-listen-addresses">.
!         It's usually better to set <varname>listen_addresses</> directly.
         </para>
        </listitem>
       </varlistentry>
***************
*** 214,221 ****
        <term><option>-l</option></term>
        <listitem>
         <para>
!     Enables secure connections using SSL.  You must have compiled with SSL
!     enabled to use this option.
         </para>
        </listitem>
       </varlistentry>
--- 218,228 ----
        <term><option>-l</option></term>
        <listitem>
         <para>
!     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,237 ****
      <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.)
         </para>
        </listitem>
       </varlistentry>
--- 238,245 ----
      <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.) Specifying this option is equivalent to setting the
!     <xref linkend="guc-max-connections"> configuration parameter.
         </para>
        </listitem>
       </varlistentry>