Mark Wong <mark...@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