Another big editing pass for consistent content and presentation.

1 files changed, 162 insertions, 188 deletions

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 181d967cbb9..f2cf072edc7 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.85 2003/02/13 05:37:43 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.86 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -20,9 +20,9 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>psql</command>
-   <arg><replaceable class="parameter">options</replaceable></arg>
+   <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
    <arg><replaceable class="parameter">dbname</replaceable>
-   <arg><replaceable class="parameter">user</replaceable></arg></arg>
+   <arg><replaceable class="parameter">username</replaceable></arg></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -69,17 +69,17 @@ PostgreSQL documentation
     </varlistentry>
 	
     <varlistentry>
-      <term><option>-c <replaceable class="parameter">query</replaceable></></term>
-      <term><option>--command <replaceable class="parameter">query</replaceable></></term>
+      <term><option>-c <replaceable class="parameter">command</replaceable></></term>
+      <term><option>--command <replaceable class="parameter">command</replaceable></></term>
       <listitem>
       <para>
       Specifies that <application>psql</application> is to execute one
-      query string, <replaceable class="parameter">query</replaceable>,
+      command string, <replaceable class="parameter">command</replaceable>,
       and then exit. This is useful in shell scripts.
       </para>
       <para>
-      <replaceable class="parameter">query</replaceable> must be either
-      a query string that is completely parsable by the backend (i.e.,
+      <replaceable class="parameter">command</replaceable> must be either
+      a command string that is completely parsable by the server (i.e.,
       it contains no <application>psql</application> specific features),
       or it is a single backslash command. Thus you cannot mix
       <acronym>SQL</acronym> and <application>psql</application>
@@ -108,7 +108,7 @@ PostgreSQL documentation
       <term><option>--echo-queries</></term>
       <listitem>
       <para>
-      Show all queries that are sent to the backend. This is equivalent
+      Show all commands that are sent to the server. This is equivalent
       to setting the variable <varname>ECHO</varname> to
       <literal>queries</literal>.
       </para>
@@ -120,7 +120,7 @@ PostgreSQL documentation
       <term><option>--echo-hidden</></term>
       <listitem>
       <para>
-      Echoes the actual queries generated by \d and other backslash
+      Echo the actual queries generated by <command>\d</command> and other backslash
       commands. You can use this if you wish to include similar
       functionality into your own programs. This is equivalent to
       setting the variable <varname>ECHO_HIDDEN</varname> from within
@@ -135,7 +135,7 @@ PostgreSQL documentation
       <listitem>
       <para>
       Use the file <replaceable class="parameter">filename</replaceable>
-      as the source of queries instead of reading queries interactively.
+      as the source of commands instead of reading commands interactively.
       After the file is processed, <application>psql</application>
       terminates. This is in many ways equivalent to the internal
       command <command>\i</command>.
@@ -179,7 +179,7 @@ PostgreSQL documentation
       <listitem>
       <para>
       Specifies the host name of the machine on which the
-      <application>postmaster</application> is running. If host begins
+      server is running. If the value begins
       with a slash, it is used as the directory for the Unix-domain
       socket.
       </para>
@@ -191,7 +191,7 @@ PostgreSQL documentation
       <term><option>--html</></term>
       <listitem>
       <para>
-      Turns on <acronym>HTML</acronym> tabular output. This is
+      Turn on <acronym>HTML</acronym> tabular output. This is
       equivalent to <literal>\pset format html</literal> or the
       <command>\H</command> command.
       </para>
@@ -203,7 +203,7 @@ PostgreSQL documentation
       <term><option>--list</></term>
       <listitem>
       <para>
-      Lists all available databases, then exits. Other non-connection
+      List all available databases, then exits. Other non-connection
       options are ignored. This is similar to the internal command
       <command>\list</command>.
       </para>
@@ -227,9 +227,8 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
       <para>
-      Specifies the TCP/IP port or, by omission, the local Unix domain
-      socket file extension on which the
-      <application>postmaster</application> is listening for
+      Specifies the TCP port or the local Unix domain
+      socket file extension on which the server is listening for
       connections. Defaults to the value of the <envar>PGPORT</envar>
       environment variable or, if not set, to the port specified at
       compile time, usually 5432.
@@ -284,7 +283,7 @@ PostgreSQL documentation
       <listitem>
       <para>
       Run in single-step mode. That means the user is prompted before
-      each query is sent to the backend, with the option to cancel
+      each command is sent to the server, with the option to cancel
       execution as well. Use this to debug scripts.
       </para>
       </listitem>
@@ -295,7 +294,7 @@ PostgreSQL documentation
       <term><option>--single-line</></term>
       <listitem>
       <para>
-      Runs in single-line mode where a newline terminates a query, as a
+      Runs in single-line mode where a newline terminates an SQL command, as a
       semicolon does.
       </para>
 
@@ -345,7 +344,7 @@ PostgreSQL documentation
       <para>
       This option is deprecated, as it is conceptually flawed.
       (Prompting for a non-default user name and prompting for a
-      password because the backend requires it are really two different
+      password because the server requires it are really two different
       things.) You are encouraged to look at the <option>-U</option> and
       <option>-W</option> options instead.
       </para>
@@ -357,7 +356,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
       <para>
-      Connects to the database as the user <replaceable
+      Connect to the database as the user <replaceable
       class="parameter">username</replaceable> instead of the default.
       (You must have permission to do so, of course.)
       </para> 
@@ -370,7 +369,7 @@ PostgreSQL documentation
       <term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
       <listitem>
       <para>
-      Performs a variable assignment, like the <command>\set</command>
+      Perform a variable assignment, like the <command>\set</command>
       internal command. Note that you must separate name and value, if
       any, by an equal sign on the command line. To unset a variable,
       leave off the equal sign. To just set a variable without a value,
@@ -386,7 +385,7 @@ PostgreSQL documentation
       <term><option>--version</></term>
       <listitem>
       <para>
-      Shows the <application>psql</application> version.
+      Show the <application>psql</application> version.
       </para>
       </listitem>
     </varlistentry>
@@ -404,11 +403,11 @@ PostgreSQL documentation
 
       <para>
       In the current version, <application>psql</application>
-      automatically issues a password prompt whenever the backend
+      automatically issues a password prompt whenever the server
       requests password authentication. Because this is currently based
       on a hack, the automatic recognition might mysteriously fail,
       hence this option to force a prompt. If no password prompt is
-      issued and the backend requires password authentication the
+      issued and the server requires password authentication the
       connection attempt will fail.
       </para>
       </listitem>
@@ -419,7 +418,7 @@ PostgreSQL documentation
       <term><option>--expanded</></term>
       <listitem>
       <para>
-      Turns on extended row format mode. This is equivalent to the
+      Turn on the extended table formatting mode. This is equivalent to the
       command <command>\x</command>.
       </para>
       </listitem>
@@ -440,7 +439,7 @@ PostgreSQL documentation
       <term><option>--help</></term>
       <listitem>
       <para>
-      Shows help about <application>psql</application> command line
+      Show help about <application>psql</application> command line
       arguments.
       </para>
       </listitem>
@@ -455,8 +454,8 @@ PostgreSQL documentation
   <para>
    <application>psql</application> returns 0 to the shell if it
    finished normally, 1 if a fatal error of its own (out of memory,
-   file not found) occurs, 2 if the connection to the backend went bad
-   and the session is not interactive, and 3 if an error occurred in a
+   file not found) occurs, 2 if the connection to the server went bad
+   and the session was not interactive, and 3 if an error occurred in a
    script and the variable <varname>ON_ERROR_STOP</varname> was set.
   </para>
  </refsect1>
@@ -495,13 +494,13 @@ PostgreSQL documentation
 
     <para>
     If the connection could not be made for any reason (e.g., insufficient
-    privileges, postmaster is not running on the server, etc.),
+    privileges, server is not running on the targeted host, etc.),
     <application>psql</application> will return an error and terminate.
     </para>
   </refsect2>
 
   <refsect2 id="R2-APP-PSQL-4">
-    <title>Entering Queries</title>
+    <title>Entering SQL Commands</title>
 
     <para>
     In normal operation, <application>psql</application> provides a
@@ -523,16 +522,16 @@ testdb=>
     </para>
 
     <para>
-    At the prompt, the user may type in <acronym>SQL</acronym> queries.
-    Ordinarily, input lines are sent to the backend when a
-    query-terminating semicolon is reached. An end of line does not
-    terminate a query! Thus queries can be spread over several lines for
-    clarity. If the query was sent and without error, the query results
+    At the prompt, the user may type in <acronym>SQL</acronym> commands.
+    Ordinarily, input lines are sent to the server when a
+    command-terminating semicolon is reached. An end of line does not
+    terminate a command.  Thus commands can be spread over several lines for
+    clarity. If the command was sent and without error, the results of the command
     are displayed on the screen.
     </para>
 
     <para>
-    Whenever a query is executed, <application>psql</application> also polls
+    Whenever a command is executed, <application>psql</application> also polls
     for asynchronous notification events generated by
     <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
     <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
@@ -586,18 +585,23 @@ testdb=>
     </para>
 
     <para>
-    Some commands take an <acronym>SQL</acronym> identifier
-    (such as a table name) as argument. These arguments follow the
-    syntax rules of <acronym>SQL</acronym> regarding double quotes: an
-    identifier without double quotes is coerced to lower-case, while
-    whitespace within double quotes is included in the argument.
+    Some commands take an <acronym>SQL</acronym> identifier (such as a
+    table name) as argument. These arguments follow the syntax rules
+    of <acronym>SQL</acronym>: Unquoted letters are forced to
+    lowercase, while double quotes (<literal>"</>) protect letters
+    from case conversion and allow incorporation of whitespace into
+    the identifier.  Within double quotes, paired double quotes reduce
+    to a single double quote in the resulting name.  For example,
+    <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>,
+    and <literal>"A weird"" name"</> becomes <literal>A weird"
+    name</>.
     </para>
 
     <para>
     Parsing for arguments stops when another unquoted backslash occurs.
     This is taken as the beginning of a new meta-command. The special
     sequence <literal>\\</literal> (two backslashes) marks the end of
-    arguments and continues parsing <acronym>SQL</acronym> queries, if
+    arguments and continues parsing <acronym>SQL</acronym> commands, if
     any. That way <acronym>SQL</acronym> and
     <application>psql</application> commands can be freely mixed on a
     line. But in any case, the arguments of a meta-command cannot
@@ -612,8 +616,8 @@ testdb=>
         <term><literal>\a</literal></term>
         <listitem>
         <para>
-	If the current table output format is unaligned, switch to aligned.
-	If it is not unaligned, set it to unaligned. This command is
+	If the current table output format is unaligned, it is switched to aligned.
+	If it is not unaligned, it is set to unaligned. This command is
 	kept for backwards compatibility. See <command>\pset</command> for a
 	general solution.
         </para>
@@ -624,8 +628,8 @@ testdb=>
        <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
        <listitem>
         <para>
-	 Change the current working directory to
-	 <replaceable>directory</replaceable>. Without argument, change
+	 Changes the current working directory to
+	 <replaceable>directory</replaceable>. Without argument, changes
 	 to the current user's home directory.
         </para>
 
@@ -641,7 +645,7 @@ testdb=>
         <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
         <listitem>
         <para>
-        Set the title of any tables being printed as the result of a
+        Sets the title of any tables being printed as the result of a
         query or unset any such title. This command is equivalent to
         <literal>\pset title <replaceable
         class="parameter">title</replaceable></literal>. (The name of
@@ -701,10 +705,10 @@ testdb=>
         <para>
         Performs a frontend (client) copy. This is an operation that
         runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
-        endterm="SQL-COPY-title"> command, but instead of the backend's
+        endterm="SQL-COPY-title"> command, but instead of the server
         reading or writing the specified file,
         <application>psql</application> reads or writes the file and
-        routes the data between the backend and the local file system.
+        routes the data between the server and the local file system.
 	This means that file accessibility and privileges are those
 	of the local user, not the server, and no SQL superuser
 	privileges are required.
@@ -712,8 +716,8 @@ testdb=>
 
 	<para>
 	The syntax of the command is similar to that of the
-	<acronym>SQL</acronym> <command>COPY</command> command (see its
-	description for the details). Note that, because of this,
+	<acronym>SQL</acronym> <command>COPY</command> command.  (See its
+	description for the details.)  Note that, because of this,
 	special parsing rules apply to the <command>\copy</command>
 	command. In particular, the variable substitution rules and
 	backslash escapes do not apply.
@@ -723,7 +727,7 @@ testdb=>
         <para>
 	This operation is not as efficient as the <acronym>SQL</acronym>
 	<command>COPY</command> command because all data must pass
-	through the client/server IP or socket connection. For large
+	through the client/server connection. For large
 	amounts of data the other technique may be preferable.
         </para>
         </tip>
@@ -732,9 +736,9 @@ testdb=>
         <para>
         Note the difference in interpretation of
         <literal>stdin</literal> and <literal>stdout</literal> between
-        frontend and backend copies: in a frontend copy these always
+        client and server copies: in a client copy these always
         refer to <application>psql</application>'s input and output
-        stream. On a backend copy <literal>stdin</literal> comes from
+        stream. On a server copy <literal>stdin</literal> comes from
         wherever the <command>COPY</command> itself came from (for
         example, a script run with the <option>-f</option> option), and
         <literal>stdout</literal> refers to the query output stream (see
@@ -792,7 +796,7 @@ testdb=>
         <para>
         Lists all available aggregate functions, together with the data
         type they operate on. If <replaceable
-        class="parameter">pattern</replaceable> (a regular expression)
+        class="parameter">pattern</replaceable>
         is specified, only matching aggregates are shown.
         </para>
         </listitem>
@@ -845,16 +849,8 @@ testdb=>
 
         <para>
         Descriptions for objects can be created with the
-        <command>COMMENT ON</command> <acronym>SQL</acronym> command.
+        <command>COMMENT</command> <acronym>SQL</acronym> command.
 	</para>
-
-        <note>
-        <para>
-        <productname>PostgreSQL</productname> stores the object
-        descriptions in the <structname>pg_description</> system table.
-        </para>
-        </note>
-
         </listitem>
       </varlistentry>
 
@@ -863,7 +859,7 @@ testdb=>
         <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
         <listitem>
         <para>
-        Lists all available domains (derived types). If <replaceable
+        Lists all available domains. If <replaceable
         class="parameter">pattern</replaceable>
         is specified, only matching domains are shown.
         </para>
@@ -907,12 +903,12 @@ testdb=>
 	order, to obtain a listing of all the matching objects.  The letter
 	S restricts the listing to system objects; without S, only non-system
 	objects are shown.
-	If <quote>+</quote> is appended to the command name, each object is
+	If <literal>+</literal> is appended to the command name, each object is
 	listed with its associated description, if any.
 	</para>
 
 	<para>
-	If a <replaceable class="parameter">pattern</replaceable> is
+	If <replaceable class="parameter">pattern</replaceable> is
 	specified, only objects whose name matches the pattern are listed.
 	</para>
 	</listitem>
@@ -948,7 +944,7 @@ testdb=>
         <listitem>
         <para>
         Lists available operators with their operand and return types.
-	If a <replaceable class="parameter">pattern</replaceable> is
+	If <replaceable class="parameter">pattern</replaceable> is
 	specified, only operators whose name matches the pattern are listed.
         </para>
         </listitem>
@@ -960,15 +956,15 @@ testdb=>
 	<listitem>
 	<para>
         Produces a list of all available tables with their
-        associated access permissions.
-	If a <replaceable class="parameter">pattern</replaceable> is
+        associated access privileges.
+	If <replaceable class="parameter">pattern</replaceable> is
 	specified, only tables whose name matches the pattern are listed.
 	</para>
 
 	<para>
 	The commands <xref linkend="SQL-GRANT"> and
 	<xref linkend="SQL-REVOKE">
-	are used to set access permissions.  See <xref linkend="SQL-GRANT">
+	are used to set access privileges.  See <xref linkend="SQL-GRANT">
 	for more information.
 	</para>
 	</listitem>
@@ -991,7 +987,7 @@ testdb=>
         <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
         <listitem>
         <para>
-        Lists all database users, or only those that match <replaceable
+        Lists all database users or only those that match <replaceable
         class="parameter">pattern</replaceable>.
         </para>
         </listitem>
@@ -1063,13 +1059,13 @@ Tue Oct 26 21:40:57 CEST 1999
 
         <listitem>
         <para>
-        Sets the client encoding.  Without an argument, this command
+        Sets the client character set encoding.  Without an argument, this command
         shows the current encoding.
         </para>
 	<note>
 	<para>
 	This command will not notice changes made directly by <command>SET
-        CLIENT_ENCODING</>.  If you use <literal>\encoding</literal>,
+        client_encoding</>.  If you use <command>\encoding</command>,
 	be sure to use it to set as well as examine the encoding.
 	</para>
 	</note>	
@@ -1083,7 +1079,7 @@ Tue Oct 26 21:40:57 CEST 1999
         <listitem>
         <para>
         Sets the field separator for unaligned query output. The default
-        is pipe (<literal>|</literal>). See also
+        is the vertical bar (<literal>|</literal>). See also
         <command>\pset</command> for a generic way of setting output
         options.
         </para>
@@ -1096,7 +1092,7 @@ Tue Oct 26 21:40:57 CEST 1999
 
         <listitem>
         <para>
-        Sends the current query input buffer to the backend and
+        Sends the current query input buffer to the server and
         optionally saves the output in <replaceable
         class="parameter">filename</replaceable> or pipes the output
         into a separate Unix shell to execute <replaceable
@@ -1112,12 +1108,12 @@ Tue Oct 26 21:40:57 CEST 1999
         <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
         <listitem>
         <para>
-        Give syntax help on the specified <acronym>SQL</acronym>
+        Gives syntax help on the specified <acronym>SQL</acronym>
         command. If <replaceable class="parameter">command</replaceable>
         is not specified, then <application>psql</application> will list
         all the commands for which syntax help is available. If
         <replaceable class="parameter">command</replaceable> is an
-        asterisk (<quote>*</quote>), then syntax help on all
+        asterisk (<literal>*</literal>), then syntax help on all
         <acronym>SQL</acronym> commands is shown.
         </para>
 
@@ -1169,8 +1165,8 @@ Tue Oct 26 21:40:57 CEST 1999
         <term><literal>\l</literal> (or <literal>\list</literal>)</term>
         <listitem>
         <para>
-        List the names, owners, and encodings of all the databases in
-        the server.  Append a <quote>+</quote> to the command name to
+        List the names, owners, and character set encodings of all the databases in
+        the server.  Append a <literal>+</literal> to the command name to
         see any descriptions for the databases as well.
         </para>
         </listitem>
@@ -1214,13 +1210,13 @@ Tue Oct 26 21:40:57 CEST 1999
 	<listitem>
 	<para>
 	Stores the file into a <productname>PostgreSQL</productname>
-	<quote>large object</quote>. Optionally, it associates the given
+	large object. Optionally, it associates the given
 	comment with the object. Example:
 <programlisting>
 foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
 lo_import 152801
 </programlisting>
-	The response indicates that the large object received object id
+	The response indicates that the large object received object ID
 	152801 which one ought to remember if one wants to access the
 	object ever again. For that reason it is recommended to always
 	associate a human-readable comment with every object. Those can
@@ -1249,7 +1245,7 @@ lo_import 152801
 	<listitem>
 	<para>
 	Shows a list of all <productname>PostgreSQL</productname>
-	<quote>large objects</quote> currently stored in the database,
+	large objects currently stored in the database,
 	along with any comments provided for them.
 	</para>
 	</listitem>
@@ -1291,8 +1287,7 @@ lo_import 152801
         class="parameter">filename</replaceable> or pipes future results
         into a separate Unix shell to execute <replaceable
         class="parameter">command</replaceable>. If no arguments are
-        specified, the query output will be reset to
-        <filename>stdout</filename>.
+        specified, the query output will be reset to the standard output.
         </para>
 
 	<para>
@@ -1349,7 +1344,7 @@ lo_import 152801
 	  </para>
 
 	  <para>
-	  <quote>Unaligned</quote> writes all fields of a tuple on a
+	  <quote>Unaligned</quote> writes all columns of a row on a
 	  line, separated by the currently active field separator. This
 	  is intended to create output that might be intended to be read
 	  in by other programs (tab-separated, comma-separated).
@@ -1385,14 +1380,14 @@ lo_import 152801
 	  <listitem>
 	  <para>
 	  Toggles between regular and expanded format. When expanded
-	  format is enabled, all output has two columns with the field
+	  format is enabled, all output has two columns with the column
 	  name on the left and the data on the right. This mode is
 	  useful if the data wouldn't fit on the screen in the normal
 	  <quote>horizontal</quote> mode.
 	  </para>
 
 	  <para>
-	  Expanded mode is supported by all four output modes.
+	  Expanded mode is supported by all four output formats.
 	  </para>
 	  </listitem>
 	  </varlistentry>
@@ -1402,7 +1397,7 @@ lo_import 152801
 	  <listitem>
 	  <para>
 	  The second argument is a string that should be printed
-	  whenever a field is null. The default is not to print
+	  whenever a column is null. The default is not to print
 	  anything, which can easily be mistaken for, say, an empty
 	  string. Thus, one might choose to write <literal>\pset null
 	  '(null)'</literal>.
@@ -1419,7 +1414,7 @@ lo_import 152801
 	  comma-separated output, which other programs might prefer. To
 	  set a tab as field separator, type <literal>\pset fieldsep
 	  '\t'</literal>. The default field separator is
-	  <literal>'|'</literal> (a <quote>pipe</quote> symbol).
+	  <literal>'|'</literal> (a vertical bar).
 	  </para>
 	  </listitem>
 	  </varlistentry>
@@ -1464,13 +1459,6 @@ lo_import 152801
 	  can be used to give your output descriptive tags. If no
 	  argument is given, the title is unset.
 	  </para>
-
-	  <note>
-	  <para>
-	  This formerly only affected <acronym>HTML</acronym> mode. You
-	  can now set titles in any output format.
-	  </para>
-	  </note>
 	  </listitem>
 	  </varlistentry>
 
@@ -1512,6 +1500,9 @@ lo_import 152801
 	  </listitem>
 	  </varlistentry>
 	</variablelist>
+        </para>
+
+        <para>
 	Illustrations on how these different formats look can be seen in
 	the <xref linkend="APP-PSQL-examples"
 	endterm="APP-PSQL-examples-title"> section.
@@ -1541,7 +1532,7 @@ lo_import 152801
         <term><literal>\q</literal></term>
         <listitem>
         <para>
-        Quit the <application>psql</application> program.
+        Quits the <application>psql</application> program.
         </para>
         </listitem>
       </varlistentry>
@@ -1608,8 +1599,9 @@ lo_import 152801
 
 	<para>
 	Valid variable names can contain characters, digits, and
-	underscores. See the section about
-	<application>psql</application> variables for details.
+	underscores. See the section <xref
+	linkend="APP-PSQL-variables"
+	endterm="APP-PSQL-variables-title"> below for details.
 	</para>
 
 	<para>
@@ -1644,7 +1636,7 @@ lo_import 152801
         <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
         <listitem>
         <para>
-        Allows you to specify options to be placed within the
+        Allows you to specify attributes to be placed within the
         <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
         output mode. This command is equivalent to <literal>\pset
         tableattr <replaceable
@@ -1680,7 +1672,7 @@ lo_import 152801
         <term><literal>\x</literal></term>
         <listitem>
         <para>
-        Toggles extended row format mode. As such it is equivalent to
+        Toggles extended table formatting mode. As such it is equivalent to
 	<literal>\pset expanded</literal>.
        </para>
        </listitem>
@@ -1692,7 +1684,7 @@ lo_import 152801
         <listitem>
         <para>
         Produces a list of all available tables with their
-        associated access permissions.
+        associated access privileges.
 	If a <replaceable class="parameter">pattern</replaceable> is
 	specified, only tables whose name matches the pattern are listed.
 	</para>
@@ -1700,13 +1692,13 @@ lo_import 152801
 	<para>
 	The commands <xref linkend="SQL-GRANT"> and
 	<xref linkend="SQL-REVOKE">
-	are used to set access permissions.  See <xref linkend="SQL-GRANT">
+	are used to set access privileges.  See <xref linkend="SQL-GRANT">
 	for more information.
 	</para>
 
 	<para>
 	This is an alias for <command>\dp</command> (<quote>display
-	permissions</quote>).
+	privileges</quote>).
         </para>
         </listitem>
       </varlistentry>
@@ -1729,8 +1721,7 @@ lo_import 152801
         <term><literal>\?</literal></term>
         <listitem>
         <para>
-        Get help information about the backslash (<quote>\</quote>)
-        commands.
+        Shows help information about the backslash commands.
         </para>
         </listitem>
       </varlistentry>
@@ -1741,31 +1732,20 @@ lo_import 152801
   <para>
    The various <literal>\d</> commands accept a <replaceable
    class="parameter">pattern</replaceable> parameter to specify the
-   object name(s) to be displayed.  Patterns are interpreted similarly
-   to SQL identifiers, in that unquoted letters are forced to lowercase,
-   while double quotes (<literal>"</>) protect letters from case conversion
-   and allow incorporation of whitespace into the identifier.  Within
-   double quotes, paired double quotes reduce to a single double quote in
-   the resulting name.  For example, <literal>FOO"BAR"BAZ</> is interpreted
-   as <literal>fooBARbaz</>, and <literal>"A weird"" name"</> becomes
-   <literal>A weird" name</>.
-  </para>
-
-  <para>
-   More interestingly, <literal>\d</> patterns allow the use of
-   <literal>*</> to mean <quote>any sequence of characters</>, and
-   <literal>?</> to mean <quote>any single character</>.  (This notation
-   is comparable to Unix shell filename patterns.)  Advanced users can
-   also use regular-expression notations such as character classes, for
-   example <literal>[0-9]</> to match <quote>any digit</>.  To make any of
-   these pattern-matching characters be interpreted literally, surround it
+   object name(s) to be displayed.  <literal>*</> means <quote>any
+   sequence of characters</> and <literal>?</> means <quote>any single
+   character</>.  (This notation is comparable to Unix shell file name
+   patterns.)  Advanced users can also use regular-expression
+   notations such as character classes, for example <literal>[0-9]</>
+   to match <quote>any digit</>.  To make any of these
+   pattern-matching characters be interpreted literally, surround it
    with double quotes.
   </para>
 
   <para>
    A pattern that contains an (unquoted) dot is interpreted as a schema
    name pattern followed by an object name pattern.  For example,
-   <literal> \dt foo*.bar*</> displays all tables in schemas whose name
+   <literal>\dt foo*.bar*</> displays all tables in schemas whose name
    starts with <literal>foo</> and whose table name 
    starts with <literal>bar</>.  If no dot appears, then the pattern
    matches only objects that are visible in the current schema search path.
@@ -1787,17 +1767,16 @@ lo_import 152801
 
     <para>
     <application>psql</application> provides variable substitution
-    features similar to common Unix command shells. This feature is new
-    and not very sophisticated, yet, but there are plans to expand it in
-    the future. Variables are simply name/value pairs, where the value
+    features similar to common Unix command shells.
+    Variables are simply name/value pairs, where the value
     can be any string of any length. To set variables, use the
     <application>psql</application> meta-command
     <command>\set</command>:
 <programlisting>
 testdb=> <userinput>\set foo bar</userinput>
 </programlisting>
-    sets the variable <quote>foo</quote> to the value
-    <quote>bar</quote>. To retrieve the content of the variable, precede
+    sets the variable <literal>foo</literal> to the value
+    <literal>bar</literal>. To retrieve the content of the variable, precede
     the name with a colon and use it as the argument of any slash
     command:
 <programlisting>
@@ -1840,6 +1819,8 @@ bar
     consist of all upper-case letters (and possibly numbers and
     underscores). To ensure maximum compatibility in the future, avoid
     such variables. A list of all specially treated variables follows.
+   </para>
+
     <variablelist>
       <varlistentry>
         <term><varname>DBNAME</varname></term>
@@ -1856,13 +1837,13 @@ bar
         <term><varname>ECHO</varname></term>
 	<listitem>
 	<para>
-	If set to <quote><literal>all</literal></quote>, all lines
+	If set to <literal>all</literal>, all lines
 	entered or from a script are written to the standard output
 	before they are parsed or executed. To specify this on program
 	start-up, use the switch <option>-a</option>. If set to
-	<quote><literal>queries</literal></quote>,
+	<literal>queries</literal>,
 	<application>psql</application> merely prints all queries as
-	they are sent to the backend. The option for this is
+	they are sent to the server. The option for this is
 	<option>-e</option>.
 	</para>
 	</listitem>
@@ -1877,7 +1858,7 @@ bar
 	<productname>PostgreSQL</productname> internals and provide
 	similar functionality in your own programs. If you set the
 	variable to the value <literal>noexec</literal>, the queries are
-	just shown but are not actually sent to the backend and
+	just shown but are not actually sent to the server and
 	executed.
 	</para>
 	</listitem>
@@ -1887,9 +1868,7 @@ bar
         <term><varname>ENCODING</varname></term>
 	<listitem>
 	<para>
-        The current client multibyte encoding. If you are not set up to
-        use multibyte characters, this variable will always contain
-        <quote>SQL_ASCII</quote>.
+        The current client character set encoding.
 	</para>
 	</listitem>
       </varlistentry>
@@ -1909,7 +1888,7 @@ bar
         <note>
         <para>
         This feature was shamelessly plagiarized from
-        <application>bash</application>.
+        <application>Bash</application>.
         </para>
         </note>
 	</listitem>
@@ -1925,7 +1904,7 @@ bar
         <note>
         <para>
         This feature was shamelessly plagiarized from
-        <application>bash</application>.
+        <application>Bash</application>.
         </para>
         </note>
 	</listitem>
@@ -1957,7 +1936,7 @@ bar
         <note>
         <para>
         This feature was shamelessly plagiarized from
-        <application>bash</application>.
+        <application>Bash</application>.
         </para>
         </note>
 	</listitem>
@@ -1982,7 +1961,7 @@ bar
 	<para>
 	If you use the <productname>PostgreSQL</productname> large
 	object interface to specially store data that does not fit into
-	one tuple, all the operations must be contained in a transaction
+	one row, all the operations must be contained in a transaction
 	block. (See the documentation of the large object interface for
 	more information.) Since <application>psql</application> has no
 	way to tell if you already have a transaction in progress when
@@ -1992,16 +1971,15 @@ bar
 	action. This action could either be to roll back any transaction
 	that might already be in progress, or to commit any such
 	transaction, or to do nothing at all. In the last case you must
-	provide your own <command>BEGIN
-	TRANSACTION</command>/<command>COMMIT</command> block or the
+	provide your own <command>BEGIN</command>/<command>COMMIT</command> block or the
 	results will be unpredictable (usually resulting in the desired
 	action's not being performed in any case).
 	</para>
 
 	<para>
 	To choose what you want to do you set this variable to one of
-	<quote>rollback</quote>, <quote>commit</quote>, or
-	<quote>nothing</quote>. The default is to roll back the
+	<literal>rollback</literal>, <literal>commit</literal>, or
+	<literal>nothing</literal>. The default is to roll back the
 	transaction. If you just want to load one or a few objects this
 	is fine. However, if you intend to transfer many large objects,
 	it might be advisable to provide one explicit transaction block
@@ -2015,7 +1993,7 @@ bar
 	<listitem>
 	<para>
 	By default, if non-interactive scripts encounter an error, such
-	as a malformed <acronym>SQL</acronym> query or internal
+	as a malformed <acronym>SQL</acronym> command or internal
 	meta-command, processing continues. This has been the
 	traditional behavior of <application>psql</application> but it
 	is sometimes not desirable. If this variable is set, script
@@ -2048,9 +2026,9 @@ bar
 	<listitem>
 	<para>
 	These specify what the prompt <application>psql</application>
-	issues is supposed to look like. See <quote><xref
+	issues is supposed to look like. See <xref
 	linkend="APP-PSQL-prompting"
-	endterm="APP-PSQL-prompting-title"></quote> below.
+	endterm="APP-PSQL-prompting-title"> below.
 	</para>
 	</listitem>
       </varlistentry>
@@ -2099,8 +2077,6 @@ bar
 
     </variablelist>
 
-    </para>
-
    </refsect3>
 
    <refsect3>
@@ -2127,7 +2103,7 @@ testdb=> <userinput>SELECT * FROM :foo;</userinput>
     A popular application of this facility is to refer to the last
     inserted <acronym>OID</acronym> in subsequent statements to build a
     foreign key scenario. Another possible use of this mechanism is to
-    copy the contents of a file into a field. First load the file into a
+    copy the contents of a file into a table column. First load the file into a
     variable and then proceed as above.
 <programlisting>
 testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
@@ -2135,8 +2111,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
 </programlisting>
     One possible problem with this approach is that <filename>my_file.txt</filename>
     might contain single quotes. These need to be escaped so that
-    they don't cause a syntax error when the third line is processed. This
-    could be done with the program <application>sed</application>:
+    they don't cause a syntax error when the second line is processed. This
+    could be done with the program <command>sed</command>:
 <programlisting>
 testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
 </programlisting>
@@ -2144,9 +2120,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     this way: After <application>psql</application> has parsed this
     line, it passes <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal>
     to the shell. The shell will do its own thing inside the double
-    quotes and execute <filename>sed</filename> with the arguments
+    quotes and execute <command>sed</command> with the arguments
     <literal>-e</literal> and <literal>s/'/\\'/g</literal>. When
-    <application>sed</application> parses this it will replace the two
+    <command>sed</command> parses this it will replace the two
     backslashes with a single one and then do the substitution. Perhaps
     at one point you thought it was great that all Unix commands use the
     same escape character. And this is ignoring the fact that you might
@@ -2157,12 +2133,12 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     </para>
 
     <para>
-    Since colons may legally appear in queries, the following rule
+    Since colons may legally appear in SQL commands, the following rule
     applies: If the variable is not set, the character sequence
     <quote>colon+name</quote> is not changed. In any case you can escape
     a colon with a backslash to protect it from interpretation. (The
     colon syntax for variables is standard <acronym>SQL</acronym> for
-    embedded query languages, such as <application>ecpg</application>.
+    embedded query languages, such as <application>ECPG</application>.
     The colon syntax for array slices and type casts are
     <productname>PostgreSQL</productname> extensions, hence the
     conflict.)
@@ -2179,17 +2155,17 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     <varname>PROMPT2</varname>, and <varname>PROMPT3</varname> contain strings
     and special escape sequences that describe the appearance of the
     prompt. Prompt 1 is the normal prompt that is issued when
-    <application>psql</application> requests a new query. Prompt 2 is
-    issued when more input is expected during query input because the
-    query was not terminated with a semicolon or a quote was not closed.
+    <application>psql</application> requests a new command. Prompt 2 is
+    issued when more input is expected during command input because the
+    command was not terminated with a semicolon or a quote was not closed.
     Prompt 3 is issued when you run an <acronym>SQL</acronym>
     <command>COPY</command> command and you are expected to type in the
-    tuples on the terminal.
+    row values on the terminal.
     </para>
 
     <para>
     The value of the respective prompt variable is printed literally,
-    except where a percent sign (<quote>%</quote>) is encountered.
+    except where a percent sign (<literal>%</literal>) is encountered.
     Depending on the next character, certain other text is substituted
     instead. Defined substitutions are:
 
@@ -2212,7 +2188,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
         <term><literal>%m</literal></term>
 	<listitem>
          <para>
-          The host name of the database server, truncated after the
+          The host name of the database server, truncated at the
           first dot, or <literal>[local]</literal> if the connection is
           over a Unix domain socket.
          </para>
@@ -2237,28 +2213,28 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
 
       <varlistentry>
         <term><literal>%~</literal></term>
-	<listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote>
+	<listitem><para>Like <literal>%/</literal>, but the output is <literal>~</literal>
          (tilde) if the database is your default database.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><literal>%#</literal></term>
 	<listitem><para>If the current user is a database superuser, then a
-         <quote>#</quote>, otherwise a <quote>&gt;</quote>.</para></listitem>
+         <literal>#</literal>, otherwise a <literal>&gt;</literal>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><literal>%R</literal></term>
 	<listitem>
 	<para>
-	In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if
-	in single-line mode, and <quote>!</quote> if the session is
+	In prompt 1 normally <literal>=</literal>, but <literal>^</literal> if
+	in single-line mode, and <literal>!</literal> if the session is
 	disconnected from the database (which can happen if
 	<command>\connect</command> fails). In prompt 2 the sequence is
-	replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
+	replaced by <literal>-</literal>, <literal>*</literal>, a single quote,
 	or a double quote, depending on whether
 	<application>psql</application> expects more input because the
-	query wasn't terminated yet, because you are inside a
+	command wasn't terminated yet, because you are inside a
 	<literal>/* ... */</literal> comment, or because you are inside
 	a quote. In prompt 3 the sequence doesn't resolve to anything.
 	</para>
@@ -2284,10 +2260,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
         <term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
 	<listitem>
 	<para>
-	The value of the <application>psql</application>, variable
+	The value of the <application>psql</application> variable
 	<replaceable class="parameter">name</replaceable>. See the
-	section <quote><xref linkend="APP-PSQL-variables"
-	endterm="APP-PSQL-variables-title"></quote> for details.
+	section <xref linkend="APP-PSQL-variables"
+	endterm="APP-PSQL-variables-title"> for details.
 	</para>
 	</listitem>
       </varlistentry>
@@ -2330,9 +2306,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     in your home directory and is reloaded when
     <application>psql</application> starts up. Tab-completion is also
     supported, although the completion logic makes no claim to be an
-    <acronym>SQL</acronym> parser. When available,
-    <application>psql</application> is automatically built to use these
-    features. If for some reason you do not like the tab completion, you
+    <acronym>SQL</acronym> parser.  If for some reason you do not like the tab completion, you
     can turn if off by putting this in a file named
     <filename>.inputrc</filename> in your home directory:
 <programlisting>
@@ -2341,7 +2315,7 @@ set disable-completion on
 $endif
 </programlisting>
     (This is not a <application>psql</application> but a
-    <application>readline</application> feature. Read its documentation
+    <application>Readline</application> feature. Read its documentation
     for further details.)
     </para>
    </refsect3>
@@ -2471,12 +2445,12 @@ $endif
       first argument of a single-letter backslash command to start
       directly after the command, without intervening whitespace. For
       compatibility this is still supported to some extent,
-      but I am not going to explain the details here as this use is
+      but were are not going to explain the details here as this use is
       discouraged.  If you get strange messages, keep this in mind.
       For example
 <programlisting>
 testdb=> <userinput>\foo</userinput>
-Field separator is "oo",
+Field separator is "oo".
 </programlisting>
       which is perhaps not what one would expect.
       </para>
@@ -2494,10 +2468,11 @@ Field separator is "oo",
 
       <listitem>
       <para>
-      Pressing Control-C during a <quote>copy in</quote> (data sent to
+      Pressing <keycombo action="simul"><keycap>Control</><keycap>C</></>
+      during a <quote>copy in</quote> (data sent to
       the server) doesn't show the most ideal of behaviors. If you get a
-      message such as <quote>COPY state must be terminated
-      first</quote>, simply reset the connection by entering <literal>\c
+      message such as <errorname>COPY state must be terminated
+      first</errorname>, simply reset the connection by entering <literal>\c
       - -</literal>.
       </para>
       </listitem>
@@ -2515,19 +2490,19 @@ Field separator is "oo",
   <application>psql</application>. If you want to learn
   <acronym>SQL</acronym> or get familiar with
   <productname>PostgreSQL</productname>, you might wish to read the
-  Tutorial that is included in the distribution.
+  &cite-tutorial;.
   </para>
   </note>
 
   <para>
-  The first example shows how to spread a query over several lines of
+  The first example shows how to spread a command over several lines of
   input. Notice the changing prompt:
 <programlisting>
 testdb=> <userinput>CREATE TABLE my_table (</userinput>
 testdb(> <userinput> first integer not null default 0,</userinput>
 testdb(> <userinput> second text</userinput>
 testdb-> <userinput>);</userinput>
-CREATE
+CREATE TABLE
 </programlisting>
   Now look at the table definition again:
 <programlisting>
@@ -2539,8 +2514,7 @@ testdb=> <userinput>\d my_table</userinput>
  second    | text    |
 
 </programlisting>
-  At this point you decide to change the prompt to something more
-  interesting:
+  Now we change the prompt to something more interesting:
 <programlisting>
 testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput>
 peter@localhost testdb=>