From 1ebff9ba81afbb885d8c34d7e4e975f5cdbe9a4a Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Tue, 11 Dec 2007 19:57:32 +0000
Subject: Make documentation of -W options more accurate and uniform.

---
 doc/src/sgml/ref/clusterdb.sgml  | 15 +++++++++++++--
 doc/src/sgml/ref/createdb.sgml   | 17 ++++++++++++++---
 doc/src/sgml/ref/createlang.sgml | 15 +++++++++++++--
 doc/src/sgml/ref/createuser.sgml | 15 +++++++++++++--
 doc/src/sgml/ref/dropdb.sgml     | 17 ++++++++++++++---
 doc/src/sgml/ref/droplang.sgml   | 17 ++++++++++++++---
 doc/src/sgml/ref/dropuser.sgml   | 18 ++++++++++++++----
 doc/src/sgml/ref/pg_dump.sgml    | 18 ++++++++++++++----
 doc/src/sgml/ref/pg_dumpall.sgml | 26 +++++++++++++++++++++-----
 doc/src/sgml/ref/pg_restore.sgml | 18 ++++++++++++++----
 doc/src/sgml/ref/psql-ref.sgml   | 25 ++++++++++++-------------
 doc/src/sgml/ref/reindexdb.sgml  | 13 ++++++++++++-
 doc/src/sgml/ref/vacuumdb.sgml   | 17 ++++++++++++++---
 doc/src/sgml/vacuumlo.sgml       | 27 ++++++++++++++++++++-------
 14 files changed, 202 insertions(+), 56 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index 15caa1affa3..2990b2c8af2 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.22 2007/06/04 10:02:40 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.23 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -164,7 +164,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>clusterdb</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>clusterdb</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>clusterdb</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 3b12e94f793..c75042c9b74 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createdb.sgml,v 1.46 2007/06/21 10:43:09 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createdb.sgml,v 1.47 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -183,7 +183,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
        <para>
-        User name to connect as
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -193,7 +193,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>createdb</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>createdb</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>createdb</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index 9441eef1de0..8383c66a8f9 100644
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.41 2007/05/15 19:43:51 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.42 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -144,7 +144,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>createlang</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>createlang</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>createlang</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index b002593a237..95283e6775a 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.50 2007/06/21 12:20:10 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.51 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -295,9 +295,20 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt (to connect to the server, not for the
+        Force <application>createuser</application> to prompt for a
+        password (for connecting to the server, not for the
         password of the new user).
        </para>
+
+       <para>
+        This option is never essential, since
+        <application>createuser</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>createuser</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
+       </para>
       </listitem>
      </varlistentry>
    </variablelist>
diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml
index b60c7a82522..daf01287fb7 100644
--- a/doc/src/sgml/ref/dropdb.sgml
+++ b/doc/src/sgml/ref/dropdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.33 2007/06/21 10:43:09 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.34 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -123,7 +123,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
        <para>
-        User name to connect as
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -133,7 +133,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>dropdb</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>dropdb</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>dropdb</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml
index c284476c2ae..ee334e13e5e 100644
--- a/doc/src/sgml/ref/droplang.sgml
+++ b/doc/src/sgml/ref/droplang.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/droplang.sgml,v 1.30 2007/03/26 17:23:36 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/droplang.sgml,v 1.31 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -142,7 +142,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
        <para>
-        User name to connect as
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -152,7 +152,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>droplang</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>droplang</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>droplang</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml
index a1d560009e3..af57135f120 100644
--- a/doc/src/sgml/ref/dropuser.sgml
+++ b/doc/src/sgml/ref/dropuser.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.38 2007/06/21 10:43:09 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.39 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -125,7 +125,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
        <para>
-        User name to connect as (not the user name to drop)
+        User name to connect as (not the user name to drop).
        </para>
       </listitem>
      </varlistentry>
@@ -135,8 +135,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt (to connect to the server, not for the
-        password of the user to be dropped).
+        Force <application>dropuser</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>dropuser</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>dropuser</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 6bb1cf4a476..fd0d56d8c0e 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.97 2007/03/26 17:23:36 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.98 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -647,7 +647,7 @@ PostgreSQL documentation
       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
       <listitem>
        <para>
-        Connect as the given user.
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -657,8 +657,18 @@ PostgreSQL documentation
       <term><option>--password</option></term>
       <listitem>
        <para>
-        Force a password prompt.  This should happen automatically if
-        the server requires password authentication.
+        Force <application>pg_dump</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>pg_dump</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>pg_dump</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 0d944278c44..a697cdbb911 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.68 2007/03/26 17:23:37 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.69 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -59,7 +59,7 @@ PostgreSQL documentation
   <para>
   <application>pg_dumpall</application> needs to connect several
   times to the <productname>PostgreSQL</productname> server (once per
-  database).  If you use password authentication it is likely to ask for
+  database).  If you use password authentication it will ask for
   a password each time. It is convenient to have a
   <filename>~/.pgpass</> file in such cases. See <xref
   linkend="libpq-pgpass"> for more information.
@@ -367,7 +367,7 @@ PostgreSQL documentation
       <term>--username=<replaceable>username</replaceable></term>
       <listitem>
        <para>
-        Connect as the given user.
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -377,8 +377,24 @@ PostgreSQL documentation
       <term>--password</term>
       <listitem>
        <para>
-        Force a password prompt.  This should happen automatically if
-        the server requires password authentication.
+        Force <application>pg_dumpall</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>pg_dumpall</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>pg_dumpall</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
+       </para>
+
+       <para>
+        Note that the password prompt will occur again for each database
+        to be dumped.  Usually, it's better to set up a
+        <filename>~/.pgpass</> file than to rely on manual password entry.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index a311affc3c3..17a99e5395e 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.71 2007/05/15 19:13:55 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.72 2007/12/11 19:57:32 tgl Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <refmeta>
@@ -458,7 +458,7 @@
       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
       <listitem>
        <para>
-        Connect as the given user.
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -468,8 +468,18 @@
       <term><option>--password</option></term>
       <listitem>
        <para>
-        Force a password prompt.  This should happen automatically if
-        the server requires password authentication.
+        Force <application>pg_restore</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>pg_restore</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>pg_restore</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 63c9c4303cb..40a02812fe1 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.197 2007/12/11 19:01:06 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.198 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -406,25 +406,24 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
       <para>
-      Forces <application>psql</application> to prompt for a
-      password before connecting to a database.  
+       Force <application>psql</application> to prompt for a
+       password before connecting to a database.  
       </para>
 
       <para>
-      <application>psql</application> should automatically prompt for a
-      password whenever the server requests password authentication.
-      However, currently password request detection is not totally
-      reliable, hence this option to force a prompt. If no password
-      prompt is issued and the server requires password authentication,
-      the connection attempt will fail.
+       This option is never essential, since <application>psql</application>
+       will automatically prompt for a password if the server demands
+       password authentication.  However, <application>psql</application>
+       will waste a connection attempt finding out that the server wants a
+       password.  In some cases it is worth typing <option>-W</> to avoid
+       the extra connection attempt.
       </para>
 
       <para>
-      This option will remain set for the entire session, even if you
-      change the database connection with the meta-command
-      <command>\connect</command>.
+       Note that this option will remain set for the entire session,
+       and so it affects uses of the meta-command
+       <command>\connect</command> as well as the initial connection attempt.
       </para>
-
       </listitem>
     </varlistentry>
 
diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index e4469bb12ef..259b1708609 100644
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -186,7 +186,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>reindexdb</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>reindexdb</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>reindexdb</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 87c34cee4b2..1e915eed5d0 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.41 2007/06/04 10:02:40 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.42 2007/12/11 19:57:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -199,7 +199,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
        <para>
-        User name to connect as
+        User name to connect as.
        </para>
       </listitem>
      </varlistentry>
@@ -209,7 +209,18 @@ PostgreSQL documentation
       <term><option>--password</></term>
       <listitem>
        <para>
-        Force password prompt.
+        Force <application>vacuumdb</application> to prompt for a
+        password before connecting to a database.  
+       </para>
+
+       <para>
+        This option is never essential, since
+        <application>vacuumdb</application> will automatically prompt
+        for a password if the server demands password authentication.
+        However, <application>vacuumdb</application> will waste a
+        connection attempt finding out that the server wants a password.
+        In some cases it is worth typing <option>-W</> to avoid the extra
+        connection attempt.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/vacuumlo.sgml b/doc/src/sgml/vacuumlo.sgml
index ab4c60551ff..4152d3f59a6 100644
--- a/doc/src/sgml/vacuumlo.sgml
+++ b/doc/src/sgml/vacuumlo.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/vacuumlo.sgml,v 1.2 2007/12/06 04:12:10 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/vacuumlo.sgml,v 1.3 2007/12/11 19:57:32 tgl Exp $ -->
 
 <sect1 id="vacuumlo">
  <title>vacuumlo</title>
@@ -38,42 +38,55 @@ vacuumlo [options] database [database2 ... databaseN]
    <varlistentry>
     <term><option>-v</option></term>
     <listitem>
-     <para>Write a lot of progress messages</para>
+     <para>Write a lot of progress messages.</para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term><option>-n</option></term>
     <listitem>
-     <para>Don't remove anything, just show what would be done</para>
+     <para>Don't remove anything, just show what would be done.</para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term><option>-U</option> <replaceable>username</></term>
     <listitem>
-     <para>Username to connect as</para>
+     <para>Username to connect as.</para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term><option>-W</option></term>
     <listitem>
-     <para>Force prompt for password (generally useless)</para>
+     <para>
+      Force <application>vacuumlo</application> to prompt for a
+      password before connecting to a database.  
+     </para>
+
+     <para>
+      This option is never essential, since
+      <application>vacuumlo</application> will automatically prompt
+      for a password if the server demands password authentication.
+      However, <application>vacuumlo</application> will waste a
+      connection attempt finding out that the server wants a password.
+      In some cases it is worth typing <option>-W</> to avoid the extra
+      connection attempt.
+     </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term><option>-h</option> <replaceable>hostname</></term>
     <listitem>
-     <para>Database server's host</para>
+     <para>Database server's host.</para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term><option>-p</option> <replaceable>port</></term>
     <listitem>
-     <para>Database server's port</para>
+     <para>Database server's port.</para>
     </listitem>
    </varlistentry>
   </variablelist>
-- 
cgit v1.2.3