Re: replication protocol documentation inconsistencies

Robert Haas wrote:
> On Wed, May 28, 2014 at 6:51 PM, Andres Freund <andres(at)2ndquadrant(dot)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