Add pg_service.conf documentation for libpq.

bmomjian · bmomjian · commit 87fa10a42613 · 2006-03-01T00:23:21.000Z
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.203 2006/02/28 22:35:35 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.204 2006/03/01 00:23:21 momjian Exp $
 -->
 
  <chapter id="libpq">
@@ -298,9 +298,7 @@ PGconn *PQconnectdb(const char *conninfo);
       Service name to use for additional parameters.  It specifies a service
       name in <filename>pg_service.conf</filename> that holds additional connection parameters.
       This allows applications to specify only a service name so connection parameters 
-      can be centrally maintained.  See 
-      <filename>share/pg_service.conf.sample</> in the installation
-      directory for information on how to set up the file.
+      can be centrally maintained. See <xref linkend="libpq-pgservice">.
      </para>
      </listitem>
     </varlistentry>
@@ -4031,6 +4029,35 @@ however.)
 </sect1>
 
 
+<sect1 id="libpq-pgservice">
+<title>The Connection Service File</title>
+
+<indexterm zone="libpq-pgservice">
+ <primary>connection service file</primary>
+</indexterm>
+<indexterm zone="libpq-pgservice">
+ <primary>pg_service.conf</primary>
+</indexterm>
+
+<para>
+The connection service file allows libpq connection parameters to be
+associated with a single service name. That service name can then be
+specified by a libpq connection, and the associated settings will be
+used. This allows connection parameters to be modified without requiring
+a recompile of the libpq application. The service name can also be
+specified using the <envar>PGSERVICE</envar> environment variable.
+</para>
+<para>
+To use this feature, copy
+<filename>share/pg_service.conf.sample</filename> to
+<filename>etc/pg_service.conf</filename> and edit the file to add
+service names and parameters. This file can be used for client-only
+installs too. The file's location can also be specified by the
+<envar>PGSYSCONFDIR</envar> environment variable.
+</para>
+</sect1>
+
+
 <sect1 id="libpq-ssl">
 <title>SSL Support</title>
 
