Thread: Re: [BUGS] Fwd: Bug#308535: postgresql-client: [psql] manual page does not document ~/.pgpass file

Bruce Momjian <pgman@candle.pha.pa.us> writes:

>     It is also convenient to have a ~/.pgpass file to avoid regularly having
>     to type in passwords. See Section 27.12 for more information.

> Is that sufficient?

It responds to the immediate complaint, but I was thinking that we ought
to add links to the relevant pages of the libpq docs in the "See Also"
parts of all of the client-application reference pages.  If the links
read like "Client Environment Variables", "Client Password File", etc
then it seems to me this would let us remove the rather incomplete
information that is in the individual reference pages today.

            regards, tom lane

Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
>
> >     It is also convenient to have a ~/.pgpass file to avoid regularly having
> >     to type in passwords. See Section 27.12 for more information.
>
> > Is that sufficient?
>
> It responds to the immediate complaint, but I was thinking that we ought
> to add links to the relevant pages of the libpq docs in the "See Also"
> parts of all of the client-application reference pages.  If the links
> read like "Client Environment Variables", "Client Password File", etc
> then it seems to me this would let us remove the rather incomplete
> information that is in the individual reference pages today.

Right, done for environment variables, and attached.  PGPASSORD mentions
.pgpass so I think we are done.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: doc/src/sgml/ref/clusterdb.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v
retrieving revision 1.16
diff -c -c -r1.16 clusterdb.sgml
*** doc/src/sgml/ref/clusterdb.sgml    29 Nov 2003 19:51:38 -0000    1.16
--- doc/src/sgml/ref/clusterdb.sgml    29 May 2005 03:27:19 -0000
***************
*** 235,240 ****
--- 235,241 ----

    <simplelist type="inline">
     <member><xref linkend="sql-cluster" endterm="sql-cluster-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/createdb.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v
retrieving revision 1.40
diff -c -c -r1.40 createdb.sgml
*** doc/src/sgml/ref/createdb.sgml    18 Jun 2004 21:47:23 -0000    1.40
--- doc/src/sgml/ref/createdb.sgml    29 May 2005 03:27:19 -0000
***************
*** 294,299 ****
--- 294,300 ----
    <simplelist type="inline">
     <member><xref linkend="app-dropdb"></member>
     <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/createlang.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v
retrieving revision 1.33
diff -c -c -r1.33 createlang.sgml
*** doc/src/sgml/ref/createlang.sgml    29 Nov 2003 19:51:38 -0000    1.33
--- doc/src/sgml/ref/createlang.sgml    29 May 2005 03:27:20 -0000
***************
*** 232,237 ****
--- 232,238 ----
    <simplelist type="inline">
     <member><xref linkend="app-droplang"></member>
     <member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/createuser.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v
retrieving revision 1.40
diff -c -c -r1.40 createuser.sgml
*** doc/src/sgml/ref/createuser.sgml    13 May 2005 16:31:43 -0000    1.40
--- doc/src/sgml/ref/createuser.sgml    29 May 2005 03:27:20 -0000
***************
*** 334,339 ****
--- 334,340 ----
    <simplelist type="inline">
     <member><xref linkend="app-dropuser"></member>
     <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/dropdb.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v
retrieving revision 1.26
diff -c -c -r1.26 dropdb.sgml
*** doc/src/sgml/ref/dropdb.sgml    29 Nov 2003 19:51:38 -0000    1.26
--- doc/src/sgml/ref/dropdb.sgml    29 May 2005 03:27:20 -0000
***************
*** 220,225 ****
--- 220,226 ----
    <simplelist type="inline">
     <member><xref linkend="app-createdb"></member>
     <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/droplang.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v
retrieving revision 1.25
diff -c -c -r1.25 droplang.sgml
*** doc/src/sgml/ref/droplang.sgml    29 Nov 2003 19:51:38 -0000    1.25
--- doc/src/sgml/ref/droplang.sgml    29 May 2005 03:27:20 -0000
***************
*** 220,225 ****
--- 220,226 ----
    <simplelist type="inline">
     <member><xref linkend="app-createlang"></member>
     <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/dropuser.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v
retrieving revision 1.31
diff -c -c -r1.31 dropuser.sgml
*** doc/src/sgml/ref/dropuser.sgml    29 Nov 2003 19:51:38 -0000    1.31
--- doc/src/sgml/ref/dropuser.sgml    29 May 2005 03:27:20 -0000
***************
*** 224,229 ****
--- 224,230 ----
    <simplelist type="inline">
     <member><xref linkend="app-createuser"></member>
     <member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/pg_dump.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v
retrieving revision 1.76
diff -c -c -r1.76 pg_dump.sgml
*** doc/src/sgml/ref/pg_dump.sgml    17 Jan 2005 04:30:37 -0000    1.76
--- doc/src/sgml/ref/pg_dump.sgml    29 May 2005 03:27:21 -0000
***************
*** 697,702 ****
--- 697,703 ----
     <member><xref linkend="app-pg-dumpall"></member>
     <member><xref linkend="app-pgrestore"></member>
     <member><xref linkend="app-psql"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Index: doc/src/sgml/ref/pg_dumpall.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v
retrieving revision 1.48
diff -c -c -r1.48 pg_dumpall.sgml
*** doc/src/sgml/ref/pg_dumpall.sgml    6 Jan 2005 18:29:08 -0000    1.48
--- doc/src/sgml/ref/pg_dumpall.sgml    29 May 2005 03:27:21 -0000
***************
*** 415,421 ****

    <para>
      <xref linkend="app-pgdump">.  Check there for details on possible
!     error conditions.
    </para>
   </refsect1>

--- 415,422 ----

    <para>
      <xref linkend="app-pgdump">.  Check there for details on possible
!     error conditions.  Also see suppored environment variables
!     (<xref linkend="libpq-envars">).
    </para>
   </refsect1>

Index: doc/src/sgml/ref/pg_restore.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v
retrieving revision 1.50
diff -c -c -r1.50 pg_restore.sgml
*** doc/src/sgml/ref/pg_restore.sgml    23 Jan 2005 00:30:31 -0000    1.50
--- doc/src/sgml/ref/pg_restore.sgml    29 May 2005 03:27:21 -0000
***************
*** 616,621 ****
--- 616,622 ----
     <member><xref linkend="app-pgdump"></member>
     <member><xref linkend="app-pg-dumpall"></member>
     <member><xref linkend="app-psql"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>
  </refentry>
Index: doc/src/sgml/ref/psql-ref.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v
retrieving revision 1.135
diff -c -c -r1.135 psql-ref.sgml
*** doc/src/sgml/ref/psql-ref.sgml    28 Apr 2005 13:09:59 -0000    1.135
--- doc/src/sgml/ref/psql-ref.sgml    29 May 2005 03:27:23 -0000
***************
*** 2759,2764 ****
--- 2759,2772 ----

   </refsect1>

+  <refsect1>
+   <title>See Also</title>
+
+   <simplelist type="inline">
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
+   </simplelist>
+  </refsect1>
+
  </refentry>

  <!-- Keep this comment at the end of the file
Index: doc/src/sgml/ref/vacuumdb.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v
retrieving revision 1.35
diff -c -c -r1.35 vacuumdb.sgml
*** doc/src/sgml/ref/vacuumdb.sgml    6 Jan 2005 18:29:08 -0000    1.35
--- doc/src/sgml/ref/vacuumdb.sgml    29 May 2005 03:27:24 -0000
***************
*** 301,306 ****
--- 301,307 ----

    <simplelist type="inline">
     <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member>
+    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
    </simplelist>
   </refsect1>

Bruce Momjian wrote:
> Right, done for environment variables, and attached.  PGPASSORD
> mentions .pgpass so I think we are done.

Have you looked at the output this creates?  The xref already creates
link text containing the section title.  You don't need to write
"Environment variables" again.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut wrote:
> Bruce Momjian wrote:
> > Right, done for environment variables, and attached.  PGPASSORD
> > mentions .pgpass so I think we are done.
>
> Have you looked at the output this creates?  The xref already creates
> link text containing the section title.  You don't need to write
> "Environment variables" again.

I did look and I see:

    http://developer.postgresql.org/docs/postgres/app-psql.html

    Environment Variables (Section 27.11)

Is that how it should look?  Should I be using different tags?  I would
rather not show the numbers but I thought that was required when linking
from the ref pages to the main docs.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073