Thread: Missing file is mentioned on page https://www.postgresql.org/docs/13/libpq-exec.html

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/13/libpq-exec.html
Description:

On page https://www.postgresql.org/docs/13/libpq-exec.html, non-existing
file is mentioned: src/include/catalog/pg_type_d.h. We fail to find it in
this catalog:
https://git.postgresql.org/gitweb/?p=postgresql.git;a=tree;f=src/include/catalog;hb=HEAD.

On Tue, Oct 27, 2020 at 10:48:00AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/13/libpq-exec.html
> Description:
> 
> On page https://www.postgresql.org/docs/13/libpq-exec.html, non-existing
> file is mentioned: src/include/catalog/pg_type_d.h. We fail to find it in
> this catalog:
> https://git.postgresql.org/gitweb/?p=postgresql.git;a=tree;f=src/include/catalog;hb=HEAD.

Uh, in my source tree that is a symlink to
src/backend/catalog/pg_type_d.h, but that file is generated by
src/backend/catalog/genbki.pl.  Does that help you?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee

Euler Taveira <euler.taveira@2ndquadrant.com> writes:
> On Tue, 27 Oct 2020 at 13:54, Bruce Momjian <bruce@momjian.us> wrote:
>> Uh, in my source tree that is a symlink to
>> src/backend/catalog/pg_type_d.h, but that file is generated by
>> src/backend/catalog/genbki.pl.  Does that help you?

> Shouldn't we replace "are defined in the file" with "are defined in the
> generated file"? That's the only place that mentions *_d.h files. Perhaps
> adding a link to BKI [1] should avoid further questions.

It'd probably confuse users more, actually.  This chapter is aimed at
users of Postgres, not developers.

From a user's viewpoint, catalog/pg_type_d.h should look pretty much
like any other installed header.  We want to point them at that, not at
pg_type.h, because the latter is painful to include in application code
that doesn't want to buy into the Postgres programming environment
altogether.

Thinking about it from the perspective of someone dealing with an
installation tree not a source tree, maybe the reference should
be to "server/catalog/pg_type_d.h".  That might help disabuse
anyone who's expecting to find it at that path in the git tree.

            regards, tom lane

On Fri, Oct 30, 2020 at 11:09:58AM -0400, Tom Lane wrote:
> Euler Taveira <euler.taveira@2ndquadrant.com> writes:
> > On Tue, 27 Oct 2020 at 13:54, Bruce Momjian <bruce@momjian.us> wrote:
> >> Uh, in my source tree that is a symlink to
> >> src/backend/catalog/pg_type_d.h, but that file is generated by
> >> src/backend/catalog/genbki.pl.  Does that help you?
> 
> > Shouldn't we replace "are defined in the file" with "are defined in the
> > generated file"? That's the only place that mentions *_d.h files. Perhaps
> > adding a link to BKI [1] should avoid further questions.
> 
> It'd probably confuse users more, actually.  This chapter is aimed at
> users of Postgres, not developers.
> 
> >From a user's viewpoint, catalog/pg_type_d.h should look pretty much
> like any other installed header.  We want to point them at that, not at
> pg_type.h, because the latter is painful to include in application code
> that doesn't want to buy into the Postgres programming environment
> altogether.
> 
> Thinking about it from the perspective of someone dealing with an
> installation tree not a source tree, maybe the reference should
> be to "server/catalog/pg_type_d.h".  That might help disabuse
> anyone who's expecting to find it at that path in the git tree.

I am confused what the "server/" prefix means in a path name.

We currently say:

    The <acronym>OID</acronym>s of the built-in data types are defined in
    the file <filename>src/include/catalog/pg_type_d.h</filename> in the
    source tree.

We could add "compiled":

    The <acronym>OID</acronym>s of the built-in data types are defined in
    the file <filename>src/include/catalog/pg_type_d.h</filename> in the
    source tree after it is compiled.
                --------------------

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee

Bruce Momjian <bruce@momjian.us> writes:
> On Fri, Oct 30, 2020 at 11:09:58AM -0400, Tom Lane wrote:
>> Thinking about it from the perspective of someone dealing with an
>> installation tree not a source tree, maybe the reference should
>> be to "server/catalog/pg_type_d.h".  That might help disabuse
>> anyone who's expecting to find it at that path in the git tree.

> I am confused what the "server/" prefix means in a path name.

That is the path underneath the installation "include" directory
at which that file will be found.

> We currently say:

>     The <acronym>OID</acronym>s of the built-in data types are defined in
>     the file <filename>src/include/catalog/pg_type_d.h</filename> in the
>     source tree.

Yeah, so also s/source tree/install tree/.

            regards, tom lane

On Tue, Nov 10, 2020 at 06:15:29PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Fri, Oct 30, 2020 at 11:09:58AM -0400, Tom Lane wrote:
> >> Thinking about it from the perspective of someone dealing with an
> >> installation tree not a source tree, maybe the reference should
> >> be to "server/catalog/pg_type_d.h".  That might help disabuse
> >> anyone who's expecting to find it at that path in the git tree.
> 
> > I am confused what the "server/" prefix means in a path name.
> 
> That is the path underneath the installation "include" directory
> at which that file will be found.

Uh, I don't see it:

    $ ls -w 80 /usr/local/pgsql/include/
    ecpg_config.h    libpq               pgtypes_date.h       server
    ecpgerrno.h      libpq-events.h      pgtypes_error.h      sql3types.h
    ecpg_informix.h  libpq-fe.h          pgtypes.h            sqlca.h
    ecpglib.h        pg_config_ext.h     pgtypes_interval.h   sqlda-compat.h
    ecpgtype.h       pg_config.h         pgtypes_numeric.h    sqlda.h
    informix         pg_config_manual.h  pgtypes_timestamp.h  sqlda-native.h
    internal         pg_config_os.h      postgres_ext.h

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee

Bruce Momjian <bruce@momjian.us> writes:
> On Tue, Nov 10, 2020 at 06:15:29PM -0500, Tom Lane wrote:
>> That is the path underneath the installation "include" directory
>> at which that file will be found.

> Uh, I don't see it:

>     $ ls -w 80 /usr/local/pgsql/include/
>     ecpg_config.h    libpq               pgtypes_date.h       server
                                                                  ^^^^^^

You didn't do "ls -R", but I have every confidence that it's underneath
there.

            regards, tom lane

On Tue, Nov 10, 2020 at 06:15:29PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Fri, Oct 30, 2020 at 11:09:58AM -0400, Tom Lane wrote:
> >> Thinking about it from the perspective of someone dealing with an
> >> installation tree not a source tree, maybe the reference should
> >> be to "server/catalog/pg_type_d.h".  That might help disabuse
> >> anyone who's expecting to find it at that path in the git tree.
> 
> > I am confused what the "server/" prefix means in a path name.
> 
> That is the path underneath the installation "include" directory
> at which that file will be found.

Yep, it's there.  I thought I checked for an include/catalog install
directory, but obviously not well enough.

> > We currently say:
> 
> >     The <acronym>OID</acronym>s of the built-in data types are defined in
> >     the file <filename>src/include/catalog/pg_type_d.h</filename> in the
> >     source tree.
> 
> Yeah, so also s/source tree/install tree/.

OK, here is a patch that mentions both.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee

On Tue, Nov 10, 2020 at 07:23:12PM -0500, Bruce Momjian wrote:
> On Tue, Nov 10, 2020 at 06:15:29PM -0500, Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.us> writes:
> > > On Fri, Oct 30, 2020 at 11:09:58AM -0400, Tom Lane wrote:
> > >> Thinking about it from the perspective of someone dealing with an
> > >> installation tree not a source tree, maybe the reference should
> > >> be to "server/catalog/pg_type_d.h".  That might help disabuse
> > >> anyone who's expecting to find it at that path in the git tree.
> > 
> > > I am confused what the "server/" prefix means in a path name.
> > 
> > That is the path underneath the installation "include" directory
> > at which that file will be found.
> 
> Yep, it's there.  I thought I checked for an include/catalog install
> directory, but obviously not well enough.
> 
> > > We currently say:
> > 
> > >     The <acronym>OID</acronym>s of the built-in data types are defined in
> > >     the file <filename>src/include/catalog/pg_type_d.h</filename> in the
> > >     source tree.
> > 
> > Yeah, so also s/source tree/install tree/.
> 
> OK, here is a patch that mentions both.

Adjusted patch applied to all branches.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee