Robert Haas wrote: > On Wed, May 28, 2014 at 6:51 PM, Andres Freund <and...@2ndquadrant.com> wrote: > > On 2014-05-21 07:29:53 -0400, Peter Eisentraut wrote:
> >> More generally, it is weird that the message formats are described > >> there, even though the rest of the protocol documentation only mentions > >> the messages by name and then describes the formats later > >> (http://www.postgresql.org/docs/devel/static/protocol-message-types.html > >> and > >> http://www.postgresql.org/docs/devel/static/protocol-message-formats.html). > >> For example, the meaning of the "(B)" code isn't described until two > >> sections later. > > > > I am not sure that makes sense. These messages cannot be sent as > > toplevel messages - they're just describing the contents of the CopyBoth > > stream after START_REPLICATION has begun. It seems wierd to add these > > 'subprotocol' messages to the toplevel protocol description. > > I see your point, but I think Peter has a good point, too. It would > be weird to document this mini-protocol mixed in with the main > protocol, and it's so short that adding a separate section for it > hardly makes sense, but it's still strange to have the mini-protocol > being documented before we've explained our conventions for how we > document wire protocol messages. Forward references are best avoided, > especially implicit ones. IMHO this mini-protocol and the CopyBoth "subprotocol" should be documented in full in a separate subsection -- maybe even have its own index entry which points to one place that documents the whole thing. We can't expect people to read the whole FE/BE protocol chapter to hunt for the hidden references to the replication protocol or the CopyBoth stream. I would put aside the "subsection too small to make sense" argument. I don't think that matters much. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers