More minor updates and copy-editing.

doc/src/sgml/client-auth.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.68 2004/11/15 06:32:13 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.69 2004/12/26 23:06:56 tgl Exp $
 -->
 
 <chapter id="client-authentication">
@@ -53,12 +53,15 @@ $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.68 2004/11/15 06:32:13 neil
   </indexterm>
 
   <para>
-   Client authentication is controlled by the file
-   <filename>pg_hba.conf</filename> in the data directory, e.g.,
-   <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
+   Client authentication is controlled by a configuration file,
+   which traditionally is named
+   <filename>pg_hba.conf</filename> and is stored in the database
+   cluster's data directory.
    (<acronym>HBA</> stands for host-based authentication.) A default
    <filename>pg_hba.conf</filename> file is installed when the data
-   directory is initialized by <command>initdb</command>.
+   directory is initialized by <command>initdb</command>.  It is
+   possible to place the authentication configuration file elsewhere,
+   however; see the <xref linkend="guc-hba-file"> configuration parameter.
   </para>
 
   <para>
@@ -151,8 +154,8 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
      <term><literal>hostnossl</literal></term>
      <listitem>
       <para>
-       This record is similar to <literal>hostssl</> but with the
-       opposite logic: it only matches connection attempts made over
+       This record type has the opposite logic to <literal>hostssl</>:
+       it only matches connection attempts made over
        TCP/IP that do not use <acronym>SSL</acronym>.
       </para>
      </listitem>
@@ -167,7 +170,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
        The value <literal>sameuser</> specifies that the record
        matches if the requested database has the same name as the
        requested user.  The value <literal>samegroup</> specifies that
-       the requested user must a member of the group with the same
+       the requested user must be a member of the group with the same
        name as the requested database.  Otherwise, this is the name of
        a specific <productname>PostgreSQL</productname> database.
        Multiple database names can be supplied by separating them with
@@ -199,20 +202,23 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
      <term><replaceable>CIDR-address</replaceable></term>
      <listitem>
       <para>
-       Specifies the client machine IP addresses that this record
+       Specifies the client machine IP address range that this record
        matches. It contains an IP address in standard dotted decimal
        notation and a CIDR mask length. (IP addresses can only be
-       specified numerically, not as domain or host names.) For example,
-       an IPv4 CIDR mask of 8 is equivalent to an IP mask of 255.0.0.0,
-       an IPv6 CIDR mask of 64 is equivalent to an IP mask of
-       ffff:ffff:ffff:ffff::. A IPv4 CIDR mask of 32 is used for single
-       hosts.
+       specified numerically, not as domain or host names.)  The mask
+       length indicates the number of high-order bits of the client
+       IP address that must match.  Bits to the right of this must
+       be zero in the given IP address.
+       There must not be any white space between the IP address, the
+       <literal>/</literal>, and the CIDR mask length.
       </para>
 
       <para>
-       A typical CIDR address is <literal>172.20.143.89/32</literal>.
-       There should be no white space between the IP address, the
-       <literal>/</literal>, and the CIDR mask length.
+       A typical <replaceable>CIDR-address</replaceable> is
+       <literal>172.20.143.89/32</literal> for a single host, or
+       <literal>172.20.143.0/24</literal> for a network.
+       To specify a single host, use a CIDR mask of 32 for IPv4 or
+       128 for IPv6.
       </para>
 
       <para>
@@ -226,7 +232,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
       </para>
 
       <para>
-       These fields only apply to <literal>host</literal>,
+       This field only applies to <literal>host</literal>,
        <literal>hostssl</literal>, and <literal>hostnossl</> records.
       </para>
      </listitem>
@@ -234,20 +240,19 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
 
     <varlistentry>
      <term><replaceable>IP-address</replaceable></term>
-     <term><replaceable>IP-masklen</replaceable></term>
+     <term><replaceable>IP-mask</replaceable></term>
      <listitem>
       <para>
-       This may be used as an alternative to the
+       These fields may be used as an alternative to the
        <replaceable>CIDR-address</replaceable> notation. Instead of
        specifying the mask length, the actual mask is specified in a
-       separate column. For example, 255.0.0.0 represents a IPv4 CIDR
-       mask length of 8, and 255.255.255.255 represents a CIDR mask
-       length of 32. The same matching logic is used as for a dotted
-       notation <replaceable>IP-mask</replaceable>.
+       separate column. For example, <literal>255.0.0.0</> represents an IPv4
+       CIDR mask length of 8, and <literal>255.255.255.255</> represents a
+       CIDR mask length of 32.
       </para>
 
       <para>
-       This field only applies to <literal>host</literal>,
+       These fields only apply to <literal>host</literal>,
        <literal>hostssl</literal>, and <literal>hostnossl</> records.
       </para>
      </listitem>
@@ -266,7 +271,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
          <term><literal>trust</></term>
          <listitem>
          <para>
-          The connection is allowed unconditionally. This method
+          Allow the connection unconditionally. This method
           allows anyone that can connect to the
           <productname>PostgreSQL</productname> database server to login as
           any <productname>PostgreSQL</productname> user they like,
@@ -280,7 +285,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         <term><literal>reject</></term>
         <listitem>
          <para>
-          The connection is rejected unconditionally. This is useful for
+          Reject the connection unconditionally. This is useful for
           <quote>filtering out</> certain hosts from a group.
          </para>
         </listitem>
@@ -290,9 +295,8 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         <term><literal>md5</></term>
         <listitem>
          <para>
-          Requires the client to supply an MD5 encrypted password for
-          authentication. This is the only method that allows encrypted
-          passwords to be stored in <structname>pg_shadow</structname>.
+          Require the client to supply an MD5-encrypted password for
+          authentication.
           See <xref linkend="auth-password"> for details.
          </para>
         </listitem>
@@ -302,9 +306,10 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         <term><literal>crypt</></term>
         <listitem>
          <para>
-          Like the <literal>md5</literal> method but uses older <function>crypt()</>
-          encryption, which is needed for pre-7.2 clients.
-          <literal>md5</literal> is preferred for 7.2 and later clients.
+          Require the client to supply a <function>crypt()</>-encrypted
+          password for authentication.
+          <literal>md5</literal> is preferred for 7.2 and later clients,
+          but pre-7.2 clients only support <literal>crypt</>.
           See <xref linkend="auth-password"> for details.
          </para>
         </listitem>
@@ -314,8 +319,10 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         <term><literal>password</></term>
         <listitem>
          <para>
-          Same as <literal>md5</>, but the password is sent in clear text over the
-          network. This should not be used on untrusted networks.
+          Require the client to supply an unencrypted password for
+          authentication.
+          Since the password is sent in clear text over the
+          network, this should not be used on untrusted networks.
           See <xref linkend="auth-password"> for details.
          </para>
         </listitem>
@@ -325,7 +332,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         <term><literal>krb4</></term>
         <listitem>
          <para>
-          Kerberos V4 is used to authenticate the user. This is only
+          Use Kerberos V4 to authenticate the user. This is only
           available for TCP/IP connections.  See <xref
           linkend="kerberos-auth"> for details.
          </para>
@@ -336,7 +343,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         <term><literal>krb5</></term>
         <listitem>
          <para>
-          Kerberos V5 is used to authenticate the user. This is only
+          Use Kerberos V5 to authenticate the user. This is only
           available for TCP/IP connections.  See <xref
           linkend="kerberos-auth"> for details.
          </para>
@@ -353,30 +360,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
           operating system) and check if the user is allowed to
           connect as the requested database user by consulting the map
           specified after the <literal>ident</literal> key word.
-         </para>
-
-         <para>
-          If you use the map <literal>sameuser</literal>, the user
-          names are required to be identical. If not, the map name is
-          looked up in the file <filename>pg_ident.conf</filename>
-          in the same directory as <filename>pg_hba.conf</filename>.
-          The connection is accepted if that file contains an
-          entry for this map name with the operating-system user name
-          and the requested <productname>PostgreSQL</productname> user
-          name.
-         </para>
-
-         <para>
-          For local connections, this only works on machines that
-          support Unix-domain socket credentials (currently
-          <systemitem class=osname>Linux</>, <systemitem
-          class=osname>FreeBSD</>, <systemitem class=osname>NetBSD</>,
-          <systemitem class=osname>OpenBSD</>, and 
-          <systemitem class=osname>BSD/OS</>).
-         </para>
-
-         <para>
-          See <xref linkend="auth-ident"> below for details.
+          See <xref linkend="auth-ident"> for details.
          </para>
         </listitem>
        </varlistentry>
@@ -402,7 +386,7 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
      <listitem>
       <para>
        The meaning of this optional field depends on the chosen
-       authentication method and is described in the next section.
+       authentication method.  Details appear below.
       </para>
      </listitem>
     </varlistentry>
@@ -423,13 +407,6 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
    range of allowed client IP addresses.
   </para>
 
-  <important>
-   <para>
-    Do not prevent the superuser from accessing the <literal>template1</literal>
-    database.  Various utility commands need access to <literal>template1</literal>.
-   </para>
-  </important>
-
   <para>
    The <filename>pg_hba.conf</filename> file is read on start-up and when
    the main server process (<command>postmaster</>) receives a
@@ -441,13 +418,13 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
   </para>
 
   <para>
-   An example of a <filename>pg_hba.conf</filename> file is shown in
+   Some examples of <filename>pg_hba.conf</filename> entries are shown in
    <xref linkend="example-pg-hba.conf">. See the next section for details on the
    different authentication methods.
   </para>
 
    <example id="example-pg-hba.conf">
-    <title>An example <filename>pg_hba.conf</filename> file</title>
+    <title>Example <filename>pg_hba.conf</filename> entries</title>
 <programlisting>
 # Allow any user on the local system to connect to any database under
 # any user name using Unix-domain sockets (the default for local
@@ -463,7 +440,7 @@ host    all         all         127.0.0.1/32          trust
 
 # The same as the last line but using a separate netmask column
 #
-# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
+# TYPE  DATABASE    USER        IP-ADDRESS    IP-MASK             METHOD
 host    all         all         127.0.0.1     255.255.255.255     trust     
 
 # Allow any user from any host with IP address 192.168.93.x to connect
@@ -473,11 +450,6 @@ host    all         all         127.0.0.1     255.255.255.255     trust
 # TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
 host    template1   all         192.168.93.0/24       ident sameuser
 
-# The same as the last line but using a separate netmask column
-#
-# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
-host    template1   all         192.168.93.0  255.255.255.0   ident sameuser
-
 # Allow a user from host 192.168.12.10 to connect to database
 # "template1" if the user's password is correctly supplied.
 # 
@@ -486,7 +458,7 @@ host    template1   all         192.168.12.10/32      md5
 
 # In the absence of preceding "host" lines, these two lines will
 # reject all connection from 192.168.54.1 (since that entry will be
-# matched first), but allow Kerberos V connections from anywhere else
+# matched first), but allow Kerberos 5 connections from anywhere else
 # on the Internet.  The zero mask means that no bits of the host IP
 # address are considered so it matches any host.
 # 
@@ -527,7 +499,7 @@ local   db1,db2,@demodbs  all                         md5
  <sect1 id="auth-methods">
   <title>Authentication methods</title>
   <para>
-   The following describes the authentication methods in more detail.
+   The following subsections describe the authentication methods in more detail.
   </para>
 
   <sect2 id="auth-trust">
@@ -538,9 +510,10 @@ local   db1,db2,@demodbs  all                         md5
     <productname>PostgreSQL</productname> assumes that anyone who can
     connect to the server is authorized to access the database with
     whatever database user they specify (including the database superuser).
-    Of course, restrictions placed in the <literal>user</> column still apply.
-    This method should only be used when there is adequate operating system-level
-    protection on connections to the server.
+    Of course, restrictions made in the <literal>database</> and
+    <literal>user</> columns still apply.
+    This method should only be used when there is adequate
+    operating-system-level protection on connections to the server.
    </para>
 
    <para>
@@ -594,7 +567,13 @@ local   db1,db2,@demodbs  all                         md5
     The password-based authentication methods are <literal>md5</>,
     <literal>crypt</>, and <literal>password</>. These methods operate
     similarly except for the way that the password is sent across the
-    connection. If you are at all concerned about password
+    connection.  But only <literal>md5</> supports encrypted
+    passwords stored in <structname>pg_shadow</structname>;
+    the other two require unencrypted passwords to be stored there.
+   </para>
+
+   <para>
+    If you are at all concerned about password
     <quote>sniffing</> attacks then <literal>md5</> is preferred, with
     <literal>crypt</> a second choice if you must support pre-7.2
     clients. Plain <literal>password</> should especially be avoided for
@@ -606,19 +585,12 @@ local   db1,db2,@demodbs  all                         md5
     <productname>PostgreSQL</productname> database passwords are
     separate from operating system user passwords. The password for
     each database user is stored in the <literal>pg_shadow</> system
-    catalog table. Passwords can be managed with the SQL
-    commands <command>CREATE USER</command> and <command>ALTER
-    USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
-    'secret';</userinput>. By default, that is, if no password has
-    been set up, the stored password is null and
-    password authentication will always fail for that user.
-   </para>
-
-   <para>
-    To restrict the set of users that are allowed to connect to
-    certain databases, list the users in the <replaceable>user</>
-    column of <filename>pg_hba.conf</filename>, as explained in the
-    previous section.
+    catalog table. Passwords can be managed with the SQL commands
+    <xref linkend="sql-createuser" endterm="sql-createuser-title"> and
+    <xref linkend="sql-alteruser" endterm="sql-alteruser-title">,
+    e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret';</userinput>.
+    By default, that is, if no password has been set up, the stored password
+    is null and password authentication will always fail for that user.
    </para>
 
   </sect2>
@@ -634,7 +606,7 @@ local   db1,db2,@demodbs  all                         md5
     <productname>Kerberos</productname> is an industry-standard secure
     authentication system suitable for distributed computing over a public
     network. A description of the <productname>Kerberos</productname> system
-    is far beyond the scope of this document; in all generality it can be
+    is far beyond the scope of this document; in full generality it can be
     quite complex (yet powerful). The <ulink
     url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos
     <acronym>FAQ</></ulink> or <ulink url="ftp://athena-dist.mit.edu">MIT
@@ -680,9 +652,9 @@ local   db1,db2,@demodbs  all                         md5
    <para>
     Make sure that your server key file is readable (and preferably
     only readable) by the <productname>PostgreSQL</productname> server
-    account.  (See also <xref linkend="postgres-user">). The location
+    account.  (See also <xref linkend="postgres-user">.) The location
     of the key file is specified by the <xref
-    linkend="guc-krb-server-keyfile"> run-time configuration
+    linkend="guc-krb-server-keyfile"> configuration
     parameter. (See also <xref linkend="runtime-config">.) The default
     is <filename>/etc/srvtab</> if you are using Kerberos 4 and
     <filename>/usr/local/pgsql/etc/krb5.keytab</> (or whichever
@@ -728,10 +700,10 @@ local   db1,db2,@demodbs  all                         md5
    </indexterm>
 
    <para>
-    The ident authentication method works by inspecting the client's
+    The ident authentication method works by obtaining the client's
     operating system user name and determining the allowed database
-    user names by using a map file that lists the permitted
-    corresponding user name pairs.  The determination of the client's
+    user names using a map file that lists the permitted
+    corresponding pairs of names.  The determination of the client's
     user name is the security-critical point, and it works differently
     depending on the connection type.
    </para>
@@ -791,14 +763,15 @@ local   db1,db2,@demodbs  all                         md5
     <para>
      On systems without <symbol>SO_PEERCRED</> requests, ident
      authentication is only available for TCP/IP connections. As a
-     work around, it is possible to specify the <systemitem
+     work-around, it is possible to specify the <systemitem
      class="systemname">localhost</> address <systemitem
      class="systemname">127.0.0.1</> and make connections to this
-     address.
+     address.  This method is trustworthy to the extent that you trust
+     the local ident server.
     </para>
     </sect3>
 
-   <sect3>
+   <sect3 id="auth-ident-maps">
     <title>Ident Maps</title>
 
    <para>
@@ -815,21 +788,26 @@ local   db1,db2,@demodbs  all                         md5
    </para>
 
    <para>
-    Ident maps
-    other than <literal>sameuser</literal> are defined in the file
-    <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm>
-    in the data directory, which contains lines of the general form:
+    Ident maps other than <literal>sameuser</literal> are defined in the
+    ident map file, which by default is named
+    <filename>pg_ident.conf</><indexterm><primary>pg_ident.conf</primary></indexterm>
+    and is stored in the
+    cluster's data directory.  (It is possible to place the map file
+    elsewhere, however; see the <xref linkend="guc-ident-file">
+    configuration parameter.)
+    The ident map file contains lines of the general form:
 <synopsis>
 <replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
 </synopsis>
-    Comments and whitespace are handled in the usual way. The
+    Comments and whitespace are handled in the same way as in
+    <filename>pg_hba.conf</>.  The
     <replaceable>map-name</> is an arbitrary name that will be used to
     refer to this mapping in <filename>pg_hba.conf</filename>. The other
     two fields specify which operating system user is allowed to connect
     as which database user. The same <replaceable>map-name</> can be
     used repeatedly to specify more user-mappings within a single map.
     There is no restriction regarding how many database users a given
-    operating system user may correspond to and vice versa.
+    operating system user may correspond to, nor vice versa.
    </para>
 
   <para>
@@ -875,7 +853,7 @@ omicron       bryanh            guest1
   </sect2>
 
   <sect2 id="auth-pam">
-   <title>PAM Authentication</title>
+   <title>PAM authentication</title>
 
    <indexterm zone="auth-pam">
     <primary>PAM</primary>
@@ -886,9 +864,9 @@ omicron       bryanh            guest1
     <literal>password</literal> except that it uses PAM (Pluggable
     Authentication Modules) as the authentication mechanism. The
     default PAM service name is <literal>postgresql</literal>. You can
-    optionally supply you own service name after the <literal>pam</>
-    key word in the file <filename>pg_hba.conf</filename>. For more information about PAM, please read
-    the <ulink
+    optionally supply your own service name after the <literal>pam</>
+    key word in the file <filename>pg_hba.conf</filename>.
+    For more information about PAM, please read the <ulink
     url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</>
     Page</ulink> and the <ulink
     url="http://www.sun.com/software/solaris/pam/"><systemitem

doc/src/sgml/install-win32.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.21 2004/12/24 19:20:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.22 2004/12/26 23:06:56 tgl Exp $
 -->
 
 <chapter id="install-win32">
@@ -11,9 +11,9 @@ $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.21 2004/12/24 19:20:18 mo
  </indexterm>
 
  <para>
-  Although <productname>PostgreSQL</productname> is written for
-  Unix-like operating systems and can be built using
-  <productname>MinGW</productname> and
+  Although a complete <productname>PostgreSQL</productname> installation
+  for <productname>Windows</> can only be built using
+  <productname>MinGW</productname> or
   <productname>Cygwin</productname>, the C client library
   (<application>libpq</application>) and the interactive terminal
   (<application>psql</application>) can be compiled using other Windows
@@ -25,10 +25,9 @@ $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.21 2004/12/24 19:20:18 mo
 
  <tip>
   <para>
-   If you are using a Windows NT-based operating system or newer you can
-   build and use all of <productname>PostgreSQL</productname> <quote>the
-   Unix way</quote> if you install the <productname>MinGW</productname>
-   toolkit first. In that case see <xref linkend="installation">.
+   Using <productname>MinGW</productname> or
+   <productname>Cygwin</productname> is preferred.  If using one of
+   those tool sets, see <xref linkend="installation">.
   </para>
  </tip>
 
@@ -110,7 +109,7 @@ $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.21 2004/12/24 19:20:18 mo
   on this machine, you will have to add the
   <filename>src\include</filename> and
   <filename>src\interfaces\libpq</filename> subdirectories of the source
-  tree to the include path in your compilers settings.
+  tree to the include path in your compiler's settings.
  </para>
 
  <para>
@@ -123,10 +122,10 @@ $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.21 2004/12/24 19:20:18 mo
   <application>psql</application> is compiled as a <quote>console
   application</>. As the Windows console windows use a different
   encoding than the rest of the system, you must take special care
-  when using 8-bit characters at the <application>psql</application>
-  prompt. When <application>psql</application> detects a problematic
+  when using 8-bit characters within <application>psql</application>.
+  If <application>psql</application> detects a problematic
   console code page, it will warn you at startup. To change the
-  console code page, two things are neccessary:
+  console code page, two things are necessary:
 
    <itemizedlist>
     <listitem>

doc/src/sgml/installation.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.220 2004/12/24 19:20:18 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.221 2004/12/26 23:06:56 tgl Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -109,7 +109,10 @@ su - postgres
       <filename>configure</>.  (On <productname>NetBSD</productname>,
       the <filename>libedit</filename> library is
       <productname>Readline</productname>-compatible and is used if
-      <filename>libreadline</filename> is not found.)
+      <filename>libreadline</filename> is not found.)  If you are using
+      a package-based Linux distribution, be aware that you need both
+      the <literal>readline</> and <literal>readline-devel</> packages,
+      if those are separate in your distribution.
      </para>
     </listitem>
 
@@ -120,14 +123,22 @@ su - postgres
        <secondary>on Windows</secondary>
       </indexterm>
 
-      To build on <productname>NT</>-based versions of
-      <productname>Windows</> like Windows XP and 2003 see
-      <filename>doc/FAQ_MINGW</>. For earlier <productname>Windows</>
-      releases see <filename>doc/FAQ_CYGWIN</>.
-
-      To build <productname>Windows</> client-only interfaces using
-      tools like <productname>Visual C++</> and <productname>Borland
-      C++</> see
+      Additional software is needed to build
+      <productname>PostgreSQL</productname> on <productname>Windows</>.
+      You can build <productname>PostgreSQL</productname> for
+      <productname>NT</>-based versions of <productname>Windows</>
+      (like Windows XP and 2003) using <productname>MinGW</productname>;
+      see <filename>doc/FAQ_MINGW</> for details.  You can also build
+      <productname>PostgreSQL</productname> using
+      <productname>Cygwin</productname>; see <filename>doc/FAQ_CYGWIN</>.
+      A <productname>Cygwin</productname>-based build will work on older
+      versions of <productname>Windows</>, but if you have a choice,
+      we recommend the <productname>MinGW</productname> approach.
+      While these are the only tool sets recommended for a complete build,
+      it is possible to build just the C client library
+      (<application>libpq</application>) and the interactive terminal
+      (<application>psql</application>) using other <productname>Windows</>
+      tool sets.  For details of that see
       <![%standalone-include[the documentation chapter "Client-Only
       Installation on Windows"]]> <![%standalone-ignore[<xref
       linkend="install-win32">]]>.
@@ -245,7 +256,7 @@ su - postgres
 
     <listitem>
      <para>
-      <application>Kerberos</>, <productname>OpenSSL</>, or
+      <application>Kerberos</>, <productname>OpenSSL</>, and/or
       <application>PAM</>, if you want to support authentication or
       encryption using these services.
      </para>
@@ -271,7 +282,7 @@ su - postgres
        <primary>yacc</primary>
       </indexterm>
 
-      <application>Flex</> and <application>Bison</>
+      GNU <application>Flex</> and <application>Bison</>
       are needed to build a CVS checkout or if you changed the actual
       scanner and parser definition files. If you need them, be sure
       to get <application>Flex</> 2.5.4 or later and
@@ -299,7 +310,7 @@ su - postgres
    25 MB, databases take about five times the amount of space that a
    flat text file with the same data would take. If you are going to
    run the regression tests you will temporarily need up to an extra
-   90 MB. Use the <command>df</command> command to check for disk
+   90 MB. Use the <command>df</command> command to check free disk
    space.
   </para>
  </sect1>
@@ -416,9 +427,11 @@ su - postgres
     <para>
      Very old versions might not have <application>pg_ctl</>.  If you
      can't find it or it doesn't work, find out the process ID of the
-     old server, for
-     example by typing <userinput>ps ax | grep postmaster</>, and
-     signal it to stop this way:
+     old server, for example by typing
+<screen>
+<userinput>ps ax | grep postmaster</userinput>
+</screen>
+     and signal it to stop this way:
 <screen>
 <userinput>kill -INT <replaceable>processID</></userinput>
 </screen>
@@ -1108,8 +1121,10 @@ All of PostgreSQL is successfully made. Ready to install.
     program, so that you can rebuild everything with <command>gmake</>
     later on. To reset the source tree to the state in which it was
     distributed, use <command>gmake distclean</>. If you are going to
-    build for several platforms from the same source tree you must do
-    this and re-configure for each build.
+    build for several platforms within the same source tree you must do
+    this and re-configure for each build.  (Alternatively, use
+    a separate build tree for each platform, so that the source tree
+    remains unmodified.)
    </para>
   </formalpara>
 

doc/src/sgml/runtime.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.299 2004/12/26 23:06:56 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -7,7 +7,7 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp
 
  <Para>
   This chapter discusses how to set up and run the database server
-  and the interactions with the operating system.
+  and its interactions with the operating system.
  </para>
 
  <sect1 id="postgres-user">
@@ -18,7 +18,7 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp
   </indexterm>
 
   <para>
-   As with any other server daemon that is connected to outside world,
+   As with any other server daemon that is accessible to the outside world,
    it is advisable to run <productname>PostgreSQL</productname> under a
    separate user account. This user account should only own the data
    that is managed by the server, and should not be shared with other
@@ -31,8 +31,8 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp
   <para>
    To add a Unix user account to your system, look for a command
    <command>useradd</command> or <command>adduser</command>. The user
-   name <systemitem>postgres</systemitem> is often used but is by no
-   means required.
+   name <systemitem>postgres</systemitem> is often used, and is assumed
+   throughout this book, but you can use another name if you like.
   </para>
  </sect1>
 
@@ -51,14 +51,14 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp
   <para>
    Before you can do anything, you must initialize a database storage
    area on disk. We call this a <firstterm>database cluster</firstterm>.
-   (<acronym>SQL</acronym> uses the term catalog cluster instead.) A
-   database cluster is a collection of databases is accessible by a
+   (<acronym>SQL</acronym> uses the term catalog cluster.) A
+   database cluster is a collection of databases that is managed by a
    single instance of a running database server. After initialization, a
    database cluster will contain a database named
    <literal>template1</literal>. As the name suggests, this will be used
    as a template for subsequently created databases; it should not be
-   used for actual work.  (See <xref linkend="managing-databases"> for information
-   about creating databases.)
+   used for actual work.  (See <xref linkend="managing-databases"> for
+   information about creating new databases within a cluster.)
   </para>
 
   <para>
@@ -71,7 +71,7 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.298 2004/12/18 18:36:33 tgl Exp
    <filename>/var/lib/pgsql/data</filename> are popular. To initialize a
    database cluster, use the command <command>initdb</command>,<indexterm><primary>initdb</></> which is
    installed with <productname>PostgreSQL</productname>. The desired
-   file system location of your database system is indicated by the
+   file system location of your database cluster is indicated by the
    <option>-D</option> option, for example
 <screen>
 <prompt>$</> <userinput>initdb -D /usr/local/pgsql/data</userinput>
@@ -107,7 +107,7 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
 
   <para>
    <command>initdb</command> will refuse to run if the data directory
-   looks like it it has already been initialized.</para>
+   looks like it has already been initialized.</para>
 
   <para>
    Because the data directory contains all the data stored in the
@@ -123,14 +123,15 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
    database and even become the database superuser. If you do not
    trust other local users, we recommend you use one of
    <command>initdb</command>'s <option>-W</option>, <option>--pwprompt</option>
-   or <option>--pwfile</option> option to assign a password to the
+   or <option>--pwfile</option> options to assign a password to the
    database superuser.<indexterm><primary>password</><secondary>of the
-   superuser</></indexterm> After <command>initdb</command>, modify
-   the <filename>pg_hba.conf</filename> file to use <literal>md5</> or
-   <literal>password</> instead of <literal>trust</> authentication
+   superuser</></indexterm>  Also, specify <option>-A md5</> or
+   <option>-A password</> so that the default <literal>trust</> authentication
+   mode is not used; or modify the generated <filename>pg_hba.conf</filename>
+   file after running <command>initdb</command>,
    <emphasis>before</> you start the server for the first time. (Other
-   approaches include using <literal>ident</literal> authentication or
-   file system permissions to restrict connections. See <xref
+   reasonable approaches include using <literal>ident</literal> authentication
+   or file system permissions to restrict connections. See <xref
    linkend="client-authentication"> for more information.)
   </para>
 
@@ -185,22 +186,23 @@ $ <userinput>postmaster -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;</
 
   <para>
    The <command>postmaster</command> also takes a number of other
-   command line options. For more information, see the reference page
+   command line options. For more information, see the
+   <xref linkend="app-postmaster"> reference page
    and <xref linkend="runtime-config"> below.
   </para>
 
   <para>
-   This shell syntax can get tedious quickly.  Therefore the shell
-   script wrapper
-   <command>pg_ctl</command><indexterm><primary>pg_ctl</primary></indexterm>
+   This shell syntax can get tedious quickly.  Therefore the wrapper
+   program
+   <xref linkend="app-pg-ctl"><indexterm><primary>pg_ctl</primary></indexterm>
    is provided to simplify some tasks.  For example:
 <programlisting>
 pg_ctl start -l logfile
 </programlisting>
    will start the server in the background and put the output into the
    named log file. The <option>-D</option> option has the same meaning
-   here as in the <command>postmaster</command>. <command>pg_ctl</command> is also
-   capable of stopping the server.
+   here as in the <command>postmaster</command>. <command>pg_ctl</command>
+   is also capable of stopping the server.
   </para>
 
   <para>
@@ -453,19 +455,20 @@ psql: could not connect to server: No such file or directory
 
    <para>
     All parameter names are case-insensitive. Every parameter takes a
-    value of one of the four types: boolean, integer, floating point,
-    and string. Boolean values are <literal>ON</literal>,
+    value of one of four types: boolean, integer, floating point,
+    or string. Boolean values may be written as <literal>ON</literal>,
     <literal>OFF</literal>, <literal>TRUE</literal>,
     <literal>FALSE</literal>, <literal>YES</literal>,
     <literal>NO</literal>, <literal>1</literal>, <literal>0</literal>
-    (case-insensitive) or any non-ambiguous prefix of these.
+    (all case-insensitive) or any unambiguous prefix of these.
    </para>
 
    <para>
     One way to set these parameters is to edit the file
-    <filename>postgresql.conf</filename><indexterm><primary>postgresql.conf</></>
-    in the data directory. (A default file is installed there.) An
-    example of what this file might look like is:
+    <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
+    which is normally kept in the data directory. (<command>initdb</>
+    installs a default copy there.) An example of what this file might look
+    like is:
 <programlisting>
 # This is a comment
 log_connections = yes
@@ -476,7 +479,7 @@ search_path = '$user, public'
     value is optional. Whitespace is insignificant and blank lines are
     ignored. Hash marks (<literal>#</literal>) introduce comments
     anywhere.  Parameter values that are not simple identifiers or
-    numbers should be single-quoted.
+    numbers must be single-quoted.
    </para>
 
    <para>
@@ -502,11 +505,14 @@ search_path = '$user, public'
 postmaster -c log_connections=yes -c log_destination='syslog'
 </programlisting>
     Command-line options override any conflicting settings in
-    <filename>postgresql.conf</filename>.
+    <filename>postgresql.conf</filename>.  Note that this means you won't
+    be able to change the value on-the-fly by editing
+    <filename>postgresql.conf</filename>, so while the command-line
+    method may be convenient, it can cost you flexibility later.
    </para>
 
    <para>
-    Occasionally it is also useful to give a command line option to
+    Occasionally it is useful to give a command line option to
     one particular session only. The environment variable
     <envar>PGOPTIONS</envar> can be used for this purpose on the
     client side:
@@ -515,18 +521,16 @@ env PGOPTIONS='-c geqo=off' psql
 </programlisting>
     (This works for any <application>libpq</>-based client application, not
     just <application>psql</application>.) Note that this won't work for
-    parameters that are fixed when the server is started, nor for
-    parameters that require superuser permissions to change (not even
-    if you are logging in as superuser).
+    parameters that are fixed when the server is started or that must be
+    specified in <filename>postgresql.conf</filename>.
    </para>
 
    <para>
     Furthermore, it is possible to assign a set of option settings to
     a user or a database.  Whenever a session is started, the default
     settings for the user and database involved are loaded.  The
-    commands <xref linkend="sql-alterdatabase"
-    endterm="sql-alterdatabase-title"> and <xref
-    linkend="sql-alteruser" endterm="sql-alteruser-title">,
+    commands <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
+    and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">,
     respectively, are used to configure these settings.  Per-database
     settings override anything received from the
     <command>postmaster</command> command-line or the configuration
@@ -546,8 +550,8 @@ SET ENABLE_SEQSCAN TO OFF;
     <command>SET</command>: for example, if they control behavior that
     cannot reasonably be changed without restarting
     <productname>PostgreSQL</productname>.  Also, some parameters can
-    be modified via <command>SET</command> by superusers, but not by
-    ordinary users.
+    be modified via <command>SET</command> or <command>ALTER</> by superusers,
+    but not by ordinary users.
    </para>
 
    <para>
@@ -567,6 +571,20 @@ SET ENABLE_SEQSCAN TO OFF;
    <sect2 id="runtime-config-file-locations">
     <title>File Locations</title>
 
+     <para>
+      In addition to the <filename>postgresql.conf</filename> file
+      already mentioned, <productname>PostgreSQL</productname> uses
+      two other manually-edited configuration files, which control
+      client authentication (their use is discussed in <xref
+      linkend="client-authentication">).
+      By default, all three configuration files are stored
+      in the database cluster's data directory.  The options described
+      in this subsection allow the configuration files to be placed elsewhere.
+      (Doing so can ease administration.  In particular it is often
+      easier to ensure that the configuration files are properly backed-up
+      when they are kept separate.)
+     </para>
+
      <variablelist>
      <varlistentry id="guc-data-directory" xreflabel="data_directory">
       <term><varname>data_directory</varname> (<type>string</type>)</term>
@@ -602,7 +620,8 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-         Specifies the configuration file for host-based authentication.
+         Specifies the configuration file for host-based authentication
+         (customarily called <filename>pg_hba.conf</>).
          This option can only be set at server start.
        </para>
       </listitem>
@@ -616,7 +635,8 @@ SET ENABLE_SEQSCAN TO OFF;
       <listitem>
        <para>
          Specifies the configuration file for
-         <application>ident</> authentication.
+         <application>ident</> authentication
+         (customarily called <filename>pg_ident.conf</>).
          This option can only be set at server start.
        </para>
       </listitem>
@@ -629,9 +649,9 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-         Specifies that the <application>postmaster</> should create an
-         additional process-id (PID) file for use by server administration
-         programs.
+        Specifies the name of an additional process-id (PID) file that the
+        <application>postmaster</> should create for use by server
+        administration programs.
         This option can only be set at server start.
        </para>
       </listitem>
@@ -639,24 +659,23 @@ SET ENABLE_SEQSCAN TO OFF;
      </variablelist>
 
      <para>
-      In a default installation, none of the above options is set explicitly
-      in the <filename>postgresql.conf</filename> file.  Instead, the
+      In a default installation, none of the above options are set explicitly.
+      Instead, the
       data directory is specified by the <option>-D</option> command-line
       option or the <envar>PGDATA</envar> environment variable, and the
-      configuration files are all placed within the data directory.
+      configuration files are all found within the data directory.
      </para>
 
      <para>
-      It is also possible to separate the configuration files from the data
-      directory, which can ease administration.  (In particular it is often
-      easier to ensure that the configuration files are properly backed-up
-      when they are kept separate.)  To do this, the <option>-D</option>
+      If you wish to keep the configuration files elsewhere than the
+      data directory, the postmaster's <option>-D</option>
       command-line option or <envar>PGDATA</envar> environment variable
       must point to the directory containing the configuration files,
-      and the <varname>data_directory</> option is set in
+      and the <varname>data_directory</> option must be set in
       <filename>postgresql.conf</filename> (or on the command line) to show
       where the data directory is actually located.  Notice that
-      <varname>data_directory</> overrides <option>-D</option> for the location
+      <varname>data_directory</> overrides <option>-D</option> and
+      <envar>PGDATA</envar> for the location
       of the data directory, but not for the location of the configuration
       files.
      </para>
@@ -756,7 +775,7 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-        Determines the number of <quote>connection slots</quote> that
+        Determines the number of connection <quote>slots</quote> that
         are reserved for connections by <productname>PostgreSQL</>
         superusers.  At most <xref linkend="guc-max-connections">
         connections can ever be active simultaneously.  Whenever the
@@ -816,8 +835,8 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-        Sets the access permissions of the Unix-domain socket.  Unix
-        domain sockets use the usual Unix file system permission set.
+        Sets the access permissions of the Unix-domain socket.  Unix-domain
+        sockets use the usual Unix file system permission set.
         The option value is expected to be a numeric mode
         specification in the form accepted by the
         <function>chmod</function> and <function>umask</function>
@@ -830,8 +849,8 @@ SET ENABLE_SEQSCAN TO OFF;
         anyone can connect. Reasonable alternatives are
         <literal>0770</literal> (only user and group, see also
         <varname>unix_socket_group</varname>) and <literal>0700</literal>
-        (only user). (Note that actually for a Unix domain socket, only write
-        permission matters and there is no point in setting or revoking
+        (only user). (Note that for a Unix-domain socket, only write
+        permission matters and so there is no point in setting or revoking
         read or execute permissions.)
        </para>
 
@@ -855,8 +874,8 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         Specifies the <productname>Rendezvous</productname> broadcast
         name.  By default, the computer name is used, specified as an
-        empty string ''.  This option is only meaningful on platforms
-        that support <productname>Rendezvous</productname>.  This
+        empty string ''.  This option is ignored if the server was not
+        compiled with <productname>Rendezvous</productname> support.  This
         option can only be set at server start.
        </para>
       </listitem>
@@ -1163,8 +1182,8 @@ SET ENABLE_SEQSCAN TO OFF;
        </para>
 
        <para>
-        If <literal>mylib</> or <literal>mylib_init</> are not found, the
-        server will fail to start.
+        If a specified library or initialization function is not found,
+        the server will fail to start.
        </para>
 
        <para>
@@ -1179,8 +1198,9 @@ SET ENABLE_SEQSCAN TO OFF;
         By preloading a shared library (and initializing it if
         applicable), the library startup time is avoided when the
         library is first used.  However, the time to start each new
-        server process may increase, even if that process never
-        uses the library.
+        server process may increase slightly, even if that process never
+        uses the library.  So this option is recommended only for
+        libraries that will be used in most sessions.
        </para>
       </listitem>
      </varlistentry>
@@ -1589,7 +1609,7 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-        Write a message to the server logs if checkpoints caused by
+        Write a message to the server log if checkpoints caused by
         the filling of checkpoint segment files happen closer together
         than this many seconds.  The default is 30 seconds.
         Zero turns off the warning.
@@ -1622,8 +1642,8 @@ SET ENABLE_SEQSCAN TO OFF;
         file.
        </para>
        <para>
-        It is important for the command to return a zero exit status only if
-        it succeeds.  Examples:
+        It is important for the command to return a zero exit status if
+        and only if it succeeds.  Examples:
 <programlisting>
 archive_command = 'cp "%p" /mnt/server/archivedir/"%f"'
 archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
@@ -1643,20 +1663,22 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
      <title>Planner Method Configuration</title>
 
       <para>
-       These configuration parameters provide a crude method for
+       These configuration parameters provide a crude method of
        influencing the query plans chosen by the query optimizer. If
        the default plan chosen by the optimizer for a particular query
        is not optimal, a temporary solution may be found by using one
        of these configuration parameters to force the optimizer to
-       choose a better plan. Other ways to improve the quality of the
-       plans chosen by the optimizer include configuring the <xref
+       choose a different plan.  Turning one of these settings off
+       permanently is seldom a good idea, however.
+       Better ways to improve the quality of the
+       plans chosen by the optimizer include adjusting the <xref
        linkend="runtime-config-query-constants"
        endterm="runtime-config-query-constants-title">, running <xref
        linkend="sql-analyze" endterm="sql-analyze-title"> more
        frequently, increasing the value of the <xref
        linkend="guc-default-statistics-target"> configuration parameter,
-       and increasing the amount of statistics collected for a
-       particular column using <command>ALTER TABLE SET
+       and increasing the amount of statistics collected for
+       specific columns using <command>ALTER TABLE SET
        STATISTICS</command>.
       </para>
 
@@ -1669,8 +1691,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       <listitem>
        <para>
         Enables or disables the query planner's use of hashed
-        aggregation plan types. The default is on. This is used for
-        debugging the query planner.
+        aggregation plan types. The default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -1683,8 +1704,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       <listitem>
        <para>
         Enables or disables the query planner's use of hash-join plan
-        types. The default is on. This is used for debugging the query
-        planner.
+        types. The default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -1700,8 +1720,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       <listitem>
        <para>
         Enables or disables the query planner's use of index-scan plan
-        types. The default is on. This is used for debugging the query
-        planner.
+        types. The default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -1714,8 +1733,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       <listitem>
        <para>
         Enables or disables the query planner's use of merge-join plan
-        types. The default is on. This is used for debugging the query
-        planner.
+        types. The default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -1731,7 +1749,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
         plans. It's not possible to suppress nested-loop joins entirely,
         but turning this variable off discourages the planner from using
         one if there are other methods available. The default is
-        on. This is used for debugging the query planner.
+        on.
        </para>
       </listitem>
      </varlistentry>
@@ -1750,7 +1768,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
         plan types. It's not possible to suppress sequential scans
         entirely, but turning this variable off discourages the planner
         from using one if there are other methods available. The
-        default is on. This is used for debugging the query planner.
+        default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -1766,7 +1784,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
         steps. It's not possible to suppress explicit sorts entirely,
         but turning this variable off discourages the planner from
         using one if there are other methods available. The default
-        is on. This is used for debugging the query planner.
+        is on.
        </para>
       </listitem>
      </varlistentry>
@@ -1779,8 +1797,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       <listitem>
        <para>
         Enables or disables the query planner's use of <acronym>TID</>
-        scan plan types. The default is on. This is used for debugging
-        the query planner.
+        scan plan types. The default is on.
        </para>
       </listitem>
      </varlistentry>
@@ -2383,6 +2400,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
         message that is logged.  Valid values are <literal>TERSE</>,
         <literal>DEFAULT</>, and <literal>VERBOSE</>, each adding more
         fields to displayed messages.
+        Only superusers can change this setting.
        </para>
       </listitem>
      </varlistentry>
@@ -2505,7 +2523,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
           <term><literal>ERROR</literal></term>
           <listitem>
            <para>
-            Reports an error that caused the current transaction to abort.
+            Reports an error that caused the current command to abort.
            </para>
           </listitem>
          </varlistentry>
@@ -2565,15 +2583,16 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       </indexterm>
       <listitem>
        <para>
-        These options enable various debugging output to be sent to
-        the client or server log. For each executed query, they print
+        These options enable various debugging output to be emitted.
+        For each executed query, they print
         the resulting parse tree, the query rewriter output, or the
         execution plan.  <varname>debug_pretty_print</varname> indents
         these displays to produce a more readable but much longer
         output format.  <varname>client_min_messages</varname> or
         <varname>log_min_messages</varname> must be
-        <literal>DEBUG1</literal> or lower to send the output to the
-        client or server logs. These options are off by default.
+        <literal>DEBUG1</literal> or lower to actually send this output
+        to the client or the server log, respectively.
+        These options are off by default.
        </para>
       </listitem>
      </varlistentry>
@@ -2585,7 +2604,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       </indexterm>
       <listitem>
        <para>
-        This outputs a line to the server logs detailing each successful
+        This outputs a line to the server log detailing each successful
         connection. This is off by default, although it is probably very
         useful. This option can only be set at server start or in the
         <filename>postgresql.conf</filename> configuration file.
@@ -2600,7 +2619,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       </indexterm>
       <listitem>
        <para>
-        This outputs a line in the server logs similar to
+        This outputs a line in the server log similar to
         <varname>log_connections</varname> but at session termination,
         and includes the duration of the session.  This is off by
         default. This option can only be set at server start or in the
@@ -2781,11 +2800,12 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       </indexterm>
       <listitem>
        <para>
-        By default, connection logs only show the IP address of the
-        connecting host. If you want it to show the host name you can
-        turn this on, but depending on your host name resolution setup
-        it might impose a non-negligible performance penalty. This
-        option can only be set at server start.
+        By default, connection log messages only show the IP address of the
+        connecting host. Turning on this option causes logging of the
+        host name as well.  Note that depending on your host name resolution
+        setup this might impose a non-negligible performance penalty. This
+        option can only be set at server start or in the
+        <filename>postgresql.conf</filename> file.
        </para>
       </listitem>
      </varlistentry>
@@ -3039,7 +3059,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       <listitem>
        <para>
         This parameter is normally true.  When set to false, it disables
-        validation of the function body string in <xref
+        validation of the function body string during <xref
         linkend="sql-createfunction"
         endterm="sql-createfunction-title">.  Disabling validation is
         occasionally useful to avoid problems such as forward
@@ -3102,7 +3122,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Windows
       </indexterm>
       <listitem>
        <para>
-        Aborts any statement that takes over the specified number of
+        Abort any statement that takes over the specified number of
         milliseconds.  A value of zero (the default) turns off the limitation.
        </para>
       </listitem>
@@ -3419,7 +3439,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         The shared lock table is sized on the assumption that at most
         <varname>max_locks_per_transaction</varname> *
         <varname>max_connections</varname> distinct objects will need to
-        be locked at any one time. The default, 64, has historically
+        be locked at any one time. (Thus, this parameter's name may be
+        confusing: it is not a hard limit on the number of locks taken
+        by any one transaction, but rather a maximum average value.)
+        The default, 64, has historically
         proven sufficient, but you might need to raise this value if you
         have clients that touch many different tables in a single
         transaction. This option can only be set at server start.
@@ -3469,7 +3492,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         <literal>advanced</>, <literal>extended</>, or <literal>basic</>.
         The default is <literal>advanced</>.  The <literal>extended</>
         setting may be useful for exact backwards compatibility with
-        pre-7.4 releases of <productname>PostgreSQL</>.
+        pre-7.4 releases of <productname>PostgreSQL</>.  See
+        <xref linkend="posix-syntax-details"> for details.
        </para>
       </listitem>
      </varlistentry>
@@ -3501,7 +3525,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       <listitem>
        <para>
         This controls whether <command>CREATE TABLE</command> and
-        <command>CREATE TABLE AS</command> will include OIDs in
+        <command>CREATE TABLE AS</command> include an OID column in
         newly-created tables, if neither <literal>WITH OIDS</literal>
         nor <literal>WITHOUT OIDS</literal> is specified. It also
         determines whether OIDs will be included in tables created by
@@ -3589,7 +3613,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
      The following <quote>parameters</> are read-only, and are determined
      when <productname>PostgreSQL</productname> is compiled or when it is
      installed. As such, they have been excluded from the sample
-     <filename>postgresql.conf</> file.  These options determine
+     <filename>postgresql.conf</> file.  These options report
      various aspects of <productname>PostgreSQL</productname> behavior
      that may be of interest to certain applications, particularly
      administrative front-ends.
@@ -3919,7 +3943,7 @@ plruby.bar = true        # generates error, unknown class name
        <para>
         Detection of a damaged page header normally causes
         <productname>PostgreSQL</> to report an error, aborting the current
-        transaction.  Setting <varname>zero_damaged_pages</> to true causes
+        command.  Setting <varname>zero_damaged_pages</> to true causes
         the system to instead report a warning, zero out the damaged page,
         and continue processing.  This behavior <emphasis>will destroy data</>,
         namely all the rows on the damaged page.  But it allows you to get
@@ -4170,7 +4194,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
        <row>
         <entry><varname>SEMVMX</></>
         <entry>Maximum value of semaphore</>
-        <entry>at least 1000 (The default is often 32767, don't change unless asked to.)</>
+        <entry>at least 1000 (The default is often 32767, don't change unless forced to)</>
        </row>
 
      </tbody>
@@ -4183,16 +4207,23 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     shared memory parameter is <varname>SHMMAX</>, the maximum size, in
     bytes, of a shared memory segment. If you get an error message from
     <function>shmget</> like <errorname>Invalid argument</>, it is
-    possible that this limit has been exceeded. The size of the required
+    likely that this limit has been exceeded. The size of the required
     shared memory segment varies both with the number of requested
     buffers (<option>-B</> option) and the number of allowed connections
     (<option>-N</> option), although the former is the most significant.
     (You can, as a temporary solution, lower these settings to eliminate
     the failure.) As a rough approximation, you can estimate the
-    required segment size by multiplying the number of buffers and the
-    block size (8 kB by default) plus ample overhead (at least half a
-    megabyte). Any error message you might get will contain the size of
-    the failed allocation request.
+    required segment size as suggested in <xref
+    linkend="sysvipc-parameters">.  Any error message you might get will
+    contain the size of the failed allocation request.
+   </para>
+
+   <para>
+    Some systems also have a limit on the total amount of shared memory in
+    the system (<varname>SHMALL</>).  Make sure this is large enough
+    for <productname>PostgreSQL</> plus any other applications that
+    are using shared memory segments.  (Caution: <varname>SHMALL</>
+    is measured in pages rather than bytes on many systems.)
    </para>
 
    <para>
@@ -4200,10 +4231,8 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     memory segments (<varname>SHMMIN</>), which should be at most
     approximately 256 kB for <productname>PostgreSQL</> (it is
     usually just 1). The maximum number of segments system-wide
-    (<varname>SHMMNI</>) or per-process (<varname>SHMSEG</>) should
-    not cause a problem unless your system has them set to zero. Some
-    systems also have a limit on the total amount of shared memory in
-    the system; see the platform-specific instructions below.
+    (<varname>SHMMNI</>) or per-process (<varname>SHMSEG</>) are unlikely
+    to cause a problem unless your system has them set to zero.
    </para>
 
    <para>
@@ -4261,15 +4290,16 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
          By default, only 4 MB of shared memory is supported. Keep in
          mind that shared memory is not pageable; it is locked in RAM.
          To increase the amount of shared memory supported by your
-         system, add the following to your kernel configuration
-         file. A <varname>SHMALL</> value of 1024 represents 4 MB of
-         shared memory. The following increases the maximum shared
-         memory area to 32 MB:
+         system, add something like the following to your kernel configuration
+         file:
 <programlisting>
 options "SHMALL=8192"
 options "SHMMAX=\(SHMALL*PAGE_SIZE\)"
 </programlisting>
-         For those running 4.3 or later, you will probably need to increase
+         <varname>SHMALL</> is measured in 4KB pages, so a value of
+         1024 represents 4 MB of shared memory. Therefore the above increases
+         the maximum shared memory area to 32 MB.
+         For those running 4.3 or later, you will probably also need to increase
          <varname>KERNEL_VIRTUAL_MB</> above the default <literal>248</>.
          Once all changes have been made, recompile the kernel, and reboot.
         </para>
@@ -4296,9 +4326,9 @@ options "SYSPTSIZE=16"
        <formalpara>
         <title>Semaphores</>
         <para>
-         You may need to increase the number of semaphores. By
-         default, <productname>PostgreSQL</> allocates 34 semaphores,
-         which is over half the default system total of 60.  Set the
+         You will probably want to increase the number of semaphores
+         as well; the default system total of 60 will only allow about
+         50 <productname>PostgreSQL</productname> connections.  Set the
          values you want in your kernel configuration file, e.g.:
 <programlisting>
 options "SEMMNI=40"
@@ -4427,10 +4457,14 @@ sysctl -w kern.sysv.shmseg
 sysctl -w kern.sysv.shmall
 </programlisting>
         In OS X 10.3, these commands have been moved to <filename>/etc/rc</>
-        and must be edited there.  Note that <filename>/etc/rc</> is usually
+        and must be edited there.  You'll need to reboot to make changes
+        take effect.  Note that <filename>/etc/rc</> is usually
         overwritten by OS X updates (such as 10.3.6 to 10.3.7) so you
         should expect to have to redo your editing after each update.
        </para>
+       <para>
+        <varname>SHMALL</> is measured in 4KB pages on this platform.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -4742,7 +4776,7 @@ sysctl -w vm.overcommit_memory=2
       This is the <firstterm>Immediate Shutdown</firstterm>, which
       will cause the <command>postmaster</command> process to send a
       <systemitem>SIGQUIT</systemitem> to all child processes and exit
-      immediately (without properly shutting itself down). The child processes
+      immediately, without properly shutting itself down. The child processes
       likewise exit immediately upon receiving
       <systemitem>SIGQUIT</systemitem>. This will lead to recovery (by
       replaying the WAL log) upon next start-up. This is recommended
@@ -4753,29 +4787,34 @@ sysctl -w vm.overcommit_memory=2
    </variablelist>
   </para>
 
-   <important>
   <para>
-     It is best not to use <systemitem>SIGKILL</systemitem> to shut down
-     the server. This will prevent the server from releasing
-     shared memory and semaphores, which may then have to be done by
-     manually.
+   The <xref linkend="app-pg-ctl"> program provides a convenient
+   interface for sending these signals to shut down the server.
   </para>
-   </important>
 
   <para>
-   The <acronym>PID</> of the <command>postmaster</command> process can be found using the
-   <command>ps</command> program, or from the file
-   <filename>postmaster.pid</filename> in the data directory. So for
+   Alternatively, you can send the signal directly using <command>kill</>.
+   The <acronym>PID</> of the <command>postmaster</command> process can be
+   found using the <command>ps</command> program, or from the file
+   <filename>postmaster.pid</filename> in the data directory. For
    example, to do a fast shutdown:
 <screen>
 $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput>
 </screen>
   </para>
+
+   <important>
     <para>
-   The program <command>pg_ctl</command> is a shell script
-   that provides a more convenient interface for shutting down the
-   server.
+     It is best not to use <systemitem>SIGKILL</systemitem> to shut down
+     the server.  Doing so will prevent the server from releasing
+     shared memory and semaphores, which may then have to be done
+     manually before a new server can be started.  Furthermore,
+     <systemitem>SIGKILL</systemitem> kills the <command>postmaster</command>
+     process without letting it relay the signal to its subprocesses,
+     so it will be necessary to kill the individual subprocesses by hand as
+     well.
     </para>
+   </important>
  </sect1>
 
  <sect1 id="ssl-tcp">
@@ -4798,10 +4837,11 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
    With <acronym>SSL</> support compiled in, the
    <productname>PostgreSQL</> server can be started with
    <acronym>SSL</> enabled by setting the parameter
-   <xref linkend="guc-ssl"> to on in <filename>postgresql.conf</>. When
+   <xref linkend="guc-ssl"> to <literal>on</> in
+   <filename>postgresql.conf</>. When
    starting in <acronym>SSL</> mode, the server will look for the
    files <filename>server.key</> and <filename>server.crt</> in the
-   data directory, which should contain the server private key
+   data directory, which must contain the server private key
    and certificate, respectively. These files must be set up correctly
    before an <acronym>SSL</>-enabled server can start. If the private key is
    protected with a passphrase, the server will prompt for the
@@ -4811,16 +4851,18 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
   <para>
    The server will listen for both standard and <acronym>SSL</>
    connections on the same TCP port, and will negotiate with any
-   connecting client on whether to use <acronym>SSL</>. See <xref
+   connecting client on whether to use <acronym>SSL</>.  By default,
+   this is at the client's option; see <xref
    linkend="auth-pg-hba-conf"> about how to set up the server to
    require use of <acronym>SSL</> for some or all connections.
   </para>
 
   <para>
    For details on how to create your server private key and certificate,
-   refer to the <productname>OpenSSL</> documentation. A simple
-   self-signed certificate can be used to get started for testing, but a
-   certificate signed by a certificate authority (<acronym>CA</>) (either one of the global
+   refer to the <productname>OpenSSL</> documentation. A
+   self-signed certificate can be used for testing, but a
+   certificate signed by a certificate authority (<acronym>CA</>)
+   (either one of the global
    <acronym>CAs</> or a local one) should be used in production so the
    client can verify the server's identity. To create a quick
    self-signed certificate, use the following
@@ -4881,7 +4923,8 @@ chmod og-rwx server.key
    One can use <application>SSH</application> to encrypt the network
    connection between clients and a
    <productname>PostgreSQL</productname> server. Done properly, this
-   provides an adequately secure network connection.
+   provides an adequately secure network connection, even for non-SSL-capable
+   clients.
   </para>
 
   <para>
@@ -4896,7 +4939,7 @@ ssh -L 3333:foo.com:5432 joe@foo.com
    The first number in the <option>-L</option> argument, 3333, is the
    port number of your end of the tunnel; it can be chosen freely. The
    second number, 5432, is the remote end of the tunnel: the port
-   number your server is using. The name or the address in between
+   number your server is using. The name or IP address between
    the port numbers is the host with the database server you are going
    to connect to. In order to connect to the database server using
    this tunnel, you connect to port 3333 on the local machine:
@@ -4905,7 +4948,15 @@ psql -h localhost -p 3333 template1
 </programlisting>
    To the database server it will then look as though you are really
    user <literal>joe@foo.com</literal> and it will use whatever
-   authentication procedure was set up for this user. In order for the
+   authentication procedure was configured for connections from this
+   user and host.  Note that the server will not think the connection is
+   SSL-encrypted, since in fact it is not encrypted between the
+   <application>SSH</application> server and the
+   <productname>PostgreSQL</productname> server.  This should not pose any
+   extra security risk as long as they are on the same machine.
+  </para>
+  <para>
+   In order for the
    tunnel setup to succeed you must be allowed to connect via
    <command>ssh</command> as <literal>joe@foo.com</literal>, just
    as if you had attempted to use <command>ssh</command> to set up a