Rewrite much of psql's \connect code, for the sake of code clarity and

to fix regressions introduced in the recent patch adding additional
\connect options. This is based on work by Volkan YAZICI, although
this version of the patch doesn't bear much resemblance to Volkan's
version.

\connect takes 4 optional arguments: database name, user name, host
name, and port number. If any of those parameters are omitted or
specified as "-", the value of that parameter from the previous
connection is used instead; if there is no previous connection,
the libpq default is used. Note that this behavior makes it
impossible to reuse the libpq defaults without quitting psql and
restarting it; I don't really see the use case for needing to do
that.

doc/src/sgml/ref/psql-ref.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.160 2006/02/13 21:29:08 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.161 2006/04/02 20:08:20 neilc Exp $
 PostgreSQL documentation
 -->
 
@@ -712,34 +712,28 @@ testdb=&gt;
         <term><literal>\connect</literal> (or <literal>\c</literal>) <literal>[ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">host</replaceable> ] [ <replaceable class="parameter">port</replaceable> ] ]</literal></term>
         <listitem>
         <para>
-        Establishes a connection to a new database and/or under a user
-        name. The previous connection is closed. If <replaceable
-        class="parameter">dbname</replaceable> is <literal>-</literal>
-        the current database name is assumed.  Similar consideration
-        applies to <replaceable class="parameter">host</replaceable> and
-        <replaceable class="parameter">port</replaceable>. 
-        </para>
-
-        <para>
-        If <replaceable class="parameter">username</replaceable> is
-        omitted the current user name is assumed. </para>
-
-        <para>
-        As a special rule, <command>\connect</command> without any
-        arguments will connect to the default database as the default
-        user (as you would have gotten by starting
-        <application>psql</application> without any arguments).
+        Establishes a new connection to a <productname>PostgreSQL</>
+        server. If the new connection is successfully made, the
+        previous connection is closed. If any of <replaceable
+        class="parameter">dbname</replaceable>, <replaceable
+        class="parameter">username</replaceable>, <replaceable
+        class="parameter">host</replaceable> or <replaceable
+        class="parameter">port</replaceable> are omitted or specified
+        as <literal>-</literal>, the value of that parameter from the
+        previous connection is used. If there is no previous
+        connection, the <application>libpq</application> default for
+        the parameter's value is used.
         </para>
 
         <para>
         If the connection attempt failed (wrong user name, access
-        denied, etc.), the previous connection will be kept if and only
-        if <application>psql</application> is in interactive mode. When
-        executing a non-interactive script, processing will immediately
-        stop with an error. This distinction was chosen as a user
-        convenience against typos on the one hand, and a safety
-        mechanism that scripts are not accidentally acting on the wrong
-        database on the other hand.
+        denied, etc.), the previous connection will only be kept if
+        <application>psql</application> is in interactive mode. When
+        executing a non-interactive script, processing will
+        immediately stop with an error. This distinction was chosen as
+        a user convenience against typos on the one hand, and a safety
+        mechanism that scripts are not accidentally acting on the
+        wrong database on the other hand.
         </para>
         </listitem>
       </varlistentry>
@@ -997,15 +991,16 @@ testdb=&gt;
         <listitem>
         <para>
         This is not the actual command name: the letters
-        <literal>i</literal>, <literal>s</literal>, <literal>t</literal>,
-        <literal>v</literal>, <literal>S</literal> stand for index,
-        sequence, table, view, and system table, respectively. You can
-        specify any or all of these letters, in any order, to obtain a
-        listing of all the matching objects.  The letter S restricts the
-        listing to system objects; without <literal>S</literal>, only
-        non-system objects are shown.  If <literal>+</literal> is appended
-        to the command name, each object is listed with its associated
-        description, if any.
+        <literal>i</literal>, <literal>s</literal>,
+        <literal>t</literal>, <literal>v</literal>,
+        <literal>S</literal> stand for index, sequence, table, view,
+        and system table, respectively. You can specify any or all of
+        these letters, in any order, to obtain a listing of all the
+        matching objects.  The letter <literal>S</literal> restricts
+        the listing to system objects; without <literal>S</literal>,
+        only non-system objects are shown.  If <literal>+</literal> is
+        appended to the command name, each object is listed with its
+        associated description, if any.
         </para>
 
         <para>
@@ -1067,10 +1062,9 @@ testdb=&gt;
         </para>
 
         <para>
-        The commands <command>GRANT</command> and
-        <command>REVOKE</command> are used to set access privileges.
-        See <xref linkend="sql-grant" endterm="sql-grant-title">
-        for more information.
+        The <xref linkend="sql-grant" endterm="sql-grant-title"> and
+        <xref linkend="sql-revoke" endterm="sql-revoke-title">
+        commands are used to set access privileges.
         </para>
         </listitem>
       </varlistentry>
@@ -1785,10 +1779,9 @@ lo_import 152801
         </para>
 
         <para>
-        The commands <command>GRANT</command> and
-        <command>REVOKE</command> are used to set access privileges.
-        See <xref linkend="sql-grant" endterm="sql-grant-title"> for
-        more information.
+        The <xref linkend="sql-grant" endterm="sql-grant-title"> and
+        <xref linkend="sql-revoke" endterm="sql-revoke-title">
+        commands are used to set access privileges.
         </para>
 
         <para>