From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Haas <robertmhaas@gmail.com>
cc: Mark Wong <markwkm@gmail.com>, Greg Stark <stark@mit.edu>,
        Chapman Flack <chap@anastigmatix.net>,
        Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>,
        PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: Re: real/float example for testlibpq3
In-reply-to: 
 <CA+TgmobLR929aHtOfC=JKqz+qzDxdYo_dssj06TyOpnU+HbT6A@mail.gmail.com>
References: <Yhf70G9OYIKueYZi@workstation-mark-wong>
 <CAExHW5tm1FyoLZXdTjdrfRO7ObuoL_p2krc65C5s8D3eWFB50g@mail.gmail.com>
 <2511609.1646061540@sss.pgh.pa.us> <621D4CF3.6090808@anastigmatix.net>
 <2746817.1646088530@sss.pgh.pa.us>
 <CAM-w4HM2t7TonV7bz+V27Vvoo0j6hN9-omDo9SHmQ7O58UFYQg@mail.gmail.com>
 <YqjH9qGaIixfZXQo@workstation-mark-wong>
 <CA+TgmobLR929aHtOfC=JKqz+qzDxdYo_dssj06TyOpnU+HbT6A@mail.gmail.com>
Comments: In-reply-to Robert Haas <robertmhaas@gmail.com>
	message dated "Thu, 16 Jun 2022 15:06:01 -0400"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <967227.1655408510.1@sss.pgh.pa.us>
Date: Thu, 16 Jun 2022 15:41:50 -0400
Message-ID: <967228.1655408510@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/967228.1655408510%40sss.pgh.pa.us>
Precedence: bulk

Robert Haas <robertmhaas@gmail.com> writes:
> On Tue, Jun 14, 2022 at 1:40 PM Mark Wong <markwkm@gmail.com> wrote:
>> I've created a function for each data type with the idea that an example
>> for handling a specific data type can be more easily reviewed by looking
>> in a single place.
>> I've added examples for REAL, TIMESTAMP WITHOUT TIME ZONE, and BOOLEAN
>> to try to illustrate how testlibpq3.sql and testlibpq3.c will grow if
>> this is a good way to go.

> I'm not sure that we want to let these test programs grow very large.
> In particular, I don't think we should let ourselves get sucked into
> adding an example for every data type under the sun -- if that's
> wanted, the solution is perhaps to add documentation for the binary
> formats, not hide impromptu documentation inside a test program.  But
> doing this much seems OK to me.

Yeah, "hiding impromptu documentation inside a test program" is what
this looks like, and I'm not sure that's a reasonable way to go.

(1) Who's going to think to look in src/test/examples/testlibpq3.c for
documentation of binary formats?

(2) The useful details are likely to get buried in notational and
portability concerns, as I think your build failure illustrates.

(3) I bet few if any packagers install these files, so that the new
info would be unavailable to many people.

I think some new appendix in the main SGML docs would be the appropriate
place if we want to provide real documentation.

			regards, tom lane