Re: Re[2]: Adding a note to protocol.sgml regarding CopyData
On Tue, Sep 25, 2018 at 4:51 AM Bradley DeJong wrote: > > On 2018-09-22, Amit Kapila wrote ... > > ... 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 > Below text is present in the section quoted by you: The special \. last line is not needed anymore, and is not sent during COPY OUT. (It is still recognized as a terminator during COPY IN, but its use is deprecated and will eventually be removed.) This email started with the need to mention this in protocol.sgml and it is already present although at a different place than the place at which it is proposed. Personally, I don't see the need to add it to more places. Does anybody else have any opinion on this matter? -- With Regards, Amit Kapila. EnterpriseDB: http://www.enterprisedb.com
Re[2]: Adding a note to protocol.sgml regarding CopyData
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]
Re[2]: Adding a note to protocol.sgml regarding CopyData
Hello Bradley & Tatsuo-san, My 0.02€ on the text: Version 2.0 of the PostgreSQL protocol In the v3.0 protocol, the 3.0 protocol version 3.0 of the copy-in/copy-out sub-protocol the V2.0 protocol. While reading nice English (I learned "holdover"), it occurs to me that references to the protocol version lacks homogeneity. Should it use v, V or version? I'd suggest to keep "the vX.0 protocol" for a short version, and "the version X.0 protocol" for long if really desired. -- Fabien.
Re[2]: Adding a note to protocol.sgml regarding CopyData
On 2018-08-25, Tatsuo Ishii wrote to the pgsql-docs mailing list ... > Hi Bradley, > Thank you for your follow up. Your patch looks good to me. > Can you please re-send your message in pgsql-hackers attaching to this thread ... > CommitFest app does not allow ... emails other than posted to pgsql-hackers. So I > decided to post to pgsql-hackers after posting to pgsql-docs. ... OK, I think this is what you wanted. Fabian's suggestion on making the removal more assertive is included in the v2 patch. On 2018-08- Bradley DeJong wrote ... >On 2018-07-27, Tatsuo Ishii wrote ... >>... I think this should be mentioned in protocol.sgml as well. ... > > I agree. It is already mentioned as one of the differences between v2 > and v3 but an implementer should not need to read that section if they > are only implementing v3. (I know I've never looked at it before.) > > Using protocol.diff as a base, I changed the phrasing to be more > prescriptive for v3 protocol implementers (don't send a final line, be > prepared to receive a final line), changed passive voice to active > voice and fixed one COPYData -> CopyData capitalization. > > I also called this out in the description of the CopyData message > format because that is where the termination line would be > transmitted. protocol.v2.patch Description: Binary data
