Re[2]: Adding a note to protocol.sgml regarding CopyData - Mailing list pgsql-hackers

Thanks for the feedback.

On 2018-09-22, Amit Kapila wrote ...
 > ... Why can't we just extend the current Note where it is currently
...

Because information about how the protocol works belongs in the protocol
documentation not in the documentation for one implementation of the
protocol.

Think of it this way, if the only full explanation of this information
was in the psqlODBC or pgJDBC documentation would you feel comfortable
just referencing it from protocol.sgml? I would not and, in my opinion,
libpq's being the reference client implementation should not change
that.

On top of that, in the libpq documentation the termination line is only
mentioned in a section titled "Obsolete Functions for COPY" which makes
it even less likely that someone working on a different implementation
of the protocol will notice it.

[strong opinion - I would object to leaving the only description in the
libpq documentation]

 > ... why do we want to duplicate the same information ...

The change to the CopyData message documentation does refer back to the
full description. My intent with the brief description of the \. line
was to include enough information so that the reader could decide
whether or not skipping back to the full description would be useful. I
think that usefulness outweighs the minor duplication.

[moderate opinion - I plan to leave it as is unless others weigh in in
favor of just keeping the reference]

But given that I don't work on libpq or even use it, I'm not comfortable
changing the documentation of 4 different libpq methods (even obsolete
methods) on my own initiative. If the committer who picks this up wants
the libpq documentation changed as part of this, that would be different
and I'd be willing to give it a shot.

[no strong feelings one way or the other - I would leave the libpq
documentation as is but could easily be swayed]

 > ... duplicate the same information in different words at three
different places ...

I count 7 different places. In the protocol docs, there is the old
mention in the "Summary of Changes since Protocol 2.0" section and the
two new mentions in the protocol definitions plus after reading through
libpq-copy.html again, I think all 4 of these sections refer to the
terminating line/end-of-copy-data marker.

     PQgetline - "... the application must check to see if a new line
consists of the two characters \., which indicates ..."
     PQgetlineAsync - "... returns -1 if the end-of-copy-data marker has
been recognized ..."
     PQputline - "... Note ...send the two characters \. as a final line
..."
     PQendcopy - "... followed by PQendcopy after the terminator line is
seen ..."

[informational - lists references to remove when a future protocol drops
the \. line entirely]