Add pg_service.conf documentation for libpq.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index e01c282a839c1d64dc247048ba702324af787226..fba7d0069952f214a5ddc0057b2fb031594b3159 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -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>
@@ -3997,6 +3995,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>