From: Tom Lane <tgl@sss.pgh.pa.us>
To: Michael Paquier <michael@paquier.xyz>
cc: "tanghy.fnst@fujitsu.com" <tanghy.fnst@fujitsu.com>,
        Bruce Momjian <bruce@momjian.us>,
        "pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Subject: Re: pg_type_d.h location incorrect
In-reply-to: <YK4A4g07AvGa9FVF@paquier.xyz>
References: <162149020918.26174.7150424047314144297@wrigleys.postgresql.org>
 <OS0PR01MB6113637F7DBED4565902A460FB249@OS0PR01MB6113.jpnprd01.prod.outlook.com>
 <1424852.1621999180@sss.pgh.pa.us>
 <OS0PR01MB61131DD84072DC0DC5E3E003FB249@OS0PR01MB6113.jpnprd01.prod.outlook.com>
 <YK4A4g07AvGa9FVF@paquier.xyz>
Comments: In-reply-to Michael Paquier <michael@paquier.xyz>
	message dated "Wed, 26 May 2021 17:03:46 +0900"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <1681208.1622080621.0@sss.pgh.pa.us>
Date: Wed, 26 May 2021 21:58:14 -0400
Message-ID: <1681252.1622080694@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/1681252.1622080694%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <1681208.1622080621.1@sss.pgh.pa.us>

Michael Paquier <michael@paquier.xyz> writes:
> On Wed, May 26, 2021 at 05:40:45AM +0000, tanghy.fnst@fujitsu.com wrote:
>> You're right, backtick notation doesn't work at my windows machine.
>> But I made the fix in accordance with the pg-doc as below. So maybe
>> we need a fix there, too?
>> 
>> https://www.postgresql.org/docs/current/libpq-pgservice.html
>> a system-wide file at `pg_config --sysconfdir`/pg_service.conf

> Using catalog/pg_type_d.h sounds enough to me as well.  While on it,
> we could adjust include/common/relpath.h in pgbuffercache.sgml?  We
> tend to include the full path for things not generated.

I doubt we can drop the reference to pg_config in libpq-pgservice.html,
because otherwise we'd have to just say "etc/" which is not very
definite.  However, we should avoid the use of backticks since that's
a platform-specific thing.

I set out to rewrite that, but the more I looked at that section the
more help it seemed to need.  I thought the para was quite confusing
about which environment variables affect what; and I also noticed
that nowhere do we explain how service-file settings interact with
other settings.  (If that had been better specified to begin with,
maybe I'd not have made the mistake fixed in ea8013854.)

So I ended up with the attached --- what do you think?

Also, looking at this, I note that "~/.pg_service.conf" is still a
platform-ism.  We could make that slightly better by writing
"$HOME/.pg_service.conf", but is that good enough?

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff; name="improve-pgservice-docs.patch";
	charset="us-ascii"
Content-ID: <1681208.1622080621.2@sss.pgh.pa.us>
Content-Description: improve-pgservice-docs.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 875950b83c..ca231f43c4 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -8091,26 +8091,30 @@ myEventProc(PGEventId evtId, void *evtInfo, void *=
passThrough)
   <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
+   specified in a libpq connection string, and the associated settings wi=
ll be
    used. This allows connection parameters to be modified without requiri=
ng
-   a recompile of the libpq application. The service name can also be
+   a recompile of the libpq-using application. The service name can also =
be
    specified using the <envar>PGSERVICE</envar> environment variable.
   </para>
 =

   <para>
-   The connection service file can be a per-user service file
-   at <filename>~/.pg_service.conf</filename> or the location
-   specified by the environment variable <envar>PGSERVICEFILE</envar>,
-   or it can be a system-wide file
-   at <filename>`pg_config --sysconfdir`/pg_service.conf</filename> or in=
 the directory
-   specified by the environment variable
-   <envar>PGSYSCONFDIR</envar>.  If service definitions with the same
-   name exist in the user and the system file, the user file takes
-   precedence.
+   Service names can be defined in either a per-user service file or a
+   system-wide file.  If the same service name exists in both the user
+   and the system file, the user file takes precedence.
+   By default, the per-user service file is located
+   at <filename>~/.pg_service.conf</filename>; this can be overridden by
+   setting the environment variable <envar>PGSERVICEFILE</envar>.
+   The system-wide file is named <filename>pg_service.conf</filename>.
+   By default it is sought in the <filename>etc</filename> directory
+   of the <productname>PostgreSQL</productname> installation
+   (use <literal>pg_config --sysconfdir</literal> to identify this
+   directory precisely).  Another directory, but not a different file
+   name, can be specified by setting the environment variable
+   <envar>PGSYSCONFDIR</envar>.
   </para>
 =

   <para>
-   The file uses an <quote>INI file</quote> format where the section
+   Either service file uses an <quote>INI file</quote> format where the s=
ection
    name is the service name and the parameters are connection
    parameters; see <xref linkend=3D"libpq-paramkeywords"/> for a list.  F=
or
    example:
@@ -8121,9 +8125,22 @@ host=3Dsomehost
 port=3D5433
 user=3Dadmin
 </programlisting>
-   An example file is provided at
+   An example file is provided in
+   the <productname>PostgreSQL</productname> installation at
    <filename>share/pg_service.conf.sample</filename>.
   </para>
+
+  <para>
+   Connection parameters obtained from a service file are combined with
+   parameters obtained from other sources.  A service file setting
+   overrides the corresponding environment variable, and in turn can be
+   overridden by a value given directly in the connection string.
+   For example, using the above service file, a connection string
+   <literal>service=3Dmydb port=3D5434</literal> will use
+   host <literal>somehost</literal>, port <literal>5434</literal>,
+   user <literal>admin</literal>, and other parameters as set by
+   environment variables or built-in defaults.
+  </para>
  </sect1>
 =

 =


------- =_aaaaaaaaaa0--