Mark Wong <markwkm@gmail.com> writes:
> On Thu, Nov 03, 2022 at 09:55:22AM -0400, Tom Lane wrote:
>> Perhaps a new chapter under "IV. Client Interfaces" is the right
>> place?
>>
>> If we wanted to get aggressive, we could move most of the nitpicky details
>> about datatype text formatting (e.g., the array quoting rules) there too.
>> I'm not set on that, but it'd make datatype.sgml smaller which could
>> hardly be a bad thing.
> I suppose figuring out exactly where to put it and how to mark it up,
> etc., in a repeatable fashion is part of the job here.
> How does this look?
> I've simply moved things around into a new "Binary Format" section with
> the few parts that I've started for some quick feedback about whether
> this is looking like the right landing place.
I took a quick look at this. The patch cannot be applied as given
because it seems to be editing binary-format.sgml from some prior
state, but that file doesn't exist at all yet. However, there's
enough visible in the patch to comment on.
Personally I'm not excited about supplying fragments of C code
like this. Those seem quite useless to non-C users, and I'm not
really sure that they'd be very helpful even for C users, because
you have to make a whole lot of assumptions about what the user
wants to do with the value. I think what *would* be helpful is
just plain prose documentation of the on-the-wire binary format.
I don't mind if you write something like
A float4 value is a 4-byte IEEE single-precision floating point
number. It is transmitted in network byte order, so you must
convert to local byte order. (C users can do this portably
using the standard ntohl() function.)
but I'm not sure an example is worth more than such a parenthetical
comment. Perhaps others disagree, though.
regards, tom lane