Re: pg_type_d.h location incorrect

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

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 will be
    used. This allows connection parameters to be modified without requiring
-   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 section
    name is the service name and the parameters are connection
    parameters; see <xref linkend="libpq-paramkeywords"/> for a list.  For
    example:
@@ -8121,9 +8125,22 @@ host=somehost
 port=5433
 user=admin
 </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=mydb port=5434</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>