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>