Re: [HACKERS] libpq documentation cleanups (repost 3)
On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian br...@momjian.us wrote: I am also attaching a few more of Leslie's changes that I think are useful. The first clarifies a confusion Leslie had about the fact that return is referencing the return value of the function and not the value returned in the pointer. Hmm. Well, if that's the confusion, I don't think inserting the words by the function is the right way to fix it - it certainly isn't returned by anything else. You could change it to say It is also possible for *errmsg to be NULL even when the return value is also NULL; this indicates... The second change is, I think, better wording. OK. The third moves the deprecated text to the start of the function description. Leslie pointed out that that is how we do it for other libpq functions, so we should move it for consistency. That seems to me to read pretty awkwardly. You could perhaps strike the chunk and the whole first paragraph and simply write PQoidStatus is an older, deprecated version of PQoidValue. It returns its result as a character string rather than an Oid, and is not thread-safe. and then cut directly to the synopsis. That would be consistent with what we've done elsewhere; moving just that one sentence is not. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
Robert Haas wrote: On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian br...@momjian.us wrote: I am also attaching a few more of Leslie's changes that I think are useful. ?The first clarifies a confusion Leslie had about the fact that return is referencing the return value of the function and not the value returned in the pointer. Hmm. Well, if that's the confusion, I don't think inserting the words by the function is the right way to fix it - it certainly isn't returned by anything else. You could change it to say It is also possible for *errmsg to be NULL even when the return value is also NULL; this indicates... The second change is, I think, better wording. OK. The third moves the deprecated text to the start of the function description. ?Leslie pointed out that that is how we do it for other libpq functions, so we should move it for consistency. That seems to me to read pretty awkwardly. You could perhaps strike the chunk and the whole first paragraph and simply write PQoidStatus is an older, deprecated version of PQoidValue. It returns its result as a character string rather than an Oid, and is not thread-safe. and then cut directly to the synopsis. That would be consistent with what we've done elsewhere; moving just that one sentence is not. OK, I have made the adjustments you mentioned with my own wording (attached and applied). Let me know of any more needed adjustments. Thanks. -- Bruce Momjian br...@momjian.ushttp://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 58e593d..fe661b8 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -972,8 +972,8 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); If literalerrmsg/ is not symbolNULL/, then literal*errmsg/ is set to symbolNULL/ on success, else to a functionmalloc/'d error string explaining the problem. (It is also possible for literal*errmsg/ to be - set to symbolNULL/ even when symbolNULL/ is returned; this indicates an out-of-memory - situation.) + set to symbolNULL/ and the function to return symbolNULL/; + this indicates an out-of-memory condition.) /para para @@ -1352,7 +1352,7 @@ ConnStatusType PQstatus(const PGconn *conn); para See the entry for functionPQconnectStartParams/, functionPQconnectStart/ and functionPQconnectPoll/ with regards to other status codes that - might be seen. + might be returned. /para /listitem /varlistentry @@ -3163,23 +3163,15 @@ Oid PQoidValue(const PGresult *res); listitem para - Returns a string with the OID of the inserted row, if the - acronymSQL/acronym command was an commandINSERT/command - that inserted exactly one row, or a commandEXECUTE/command of - a prepared statement consisting of a suitable - commandINSERT/command. (The string will be literal0/ if - the commandINSERT/command did not insert exactly one row, or - if the target table does not have OIDs.) If the command was not - an commandINSERT/command, returns an empty string. + This function is deprecated in favor of + functionPQoidValue/function and is not thread-safe. + It returns a string with the OID of the inserted row, while + functionPQoidValue/function returns the OID value. synopsis char *PQoidStatus(const PGresult *res); /synopsis /para - para - This function is deprecated in favor of - functionPQoidValue/function. It is not thread-safe. - /para /listitem /varlistentry /variablelist -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
[HACKERS] libpq documentation cleanups (repost 3)
The attached patch is a collection of libpq documentation cleanups recommended in a list of changes emailed to me by Leslie S Satenstein. Leslie found a number of places our libpq documentation that were unclear or awkward, and this diff generated by me attempts to address them. I have already updated the documentation proofreading wiki: http://wiki.postgresql.org/wiki/Documentation_Proofreading -- Bruce Momjian br...@momjian.ushttp://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + /pgpatches/libpq.gz Description: GNU Zip compressed data -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian br...@momjian.us wrote: The attached patch is a collection of libpq documentation cleanups recommended in a list of changes emailed to me by Leslie S Satenstein. Leslie found a number of places our libpq documentation that were unclear or awkward, and this diff generated by me attempts to address them. I have already updated the documentation proofreading wiki: http://wiki.postgresql.org/wiki/Documentation_Proofreading I don't think changing see below to refer below or call to execute is an improvement; even if we did that uniformly throughout our documentation, surely future editors are going to reuse those phrasings. A lot of these other changes look pretty dubious too, although some seem worthwhile. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
2011/1/12 Robert Haas robertmh...@gmail.com On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian br...@momjian.us wrote: The attached patch is a collection of libpq documentation cleanups recommended in a list of changes emailed to me by Leslie S Satenstein. Leslie found a number of places our libpq documentation that were unclear or awkward, and this diff generated by me attempts to address them. I have already updated the documentation proofreading wiki: http://wiki.postgresql.org/wiki/Documentation_Proofreading I don't think changing see below to refer below or call to execute is an improvement; even if we did that uniformly throughout our documentation, surely future editors are going to reuse those phrasings. A lot of these other changes look pretty dubious too, although some seem worthwhile. I propose to change backend server to backend or server. Robert, you mentioned that backend server phrase is suggest interchangeability of backend or server but there is no term backend server. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers -- // Dmitriy.
Re: [HACKERS] libpq documentation cleanups (repost 3)
Robert Haas wrote: On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian br...@momjian.us wrote: The attached patch is a collection of libpq documentation cleanups recommended in a list of changes emailed to me by Leslie S Satenstein. Leslie found a number of places our libpq documentation that were unclear or awkward, and this diff generated by me attempts to address them. I have already updated the documentation proofreading wiki: ? ? ? ?http://wiki.postgresql.org/wiki/Documentation_Proofreading I don't think changing see below to refer below or call to execute is an improvement; even if we did that uniformly throughout our documentation, surely future editors are going to reuse those phrasings. A lot of these other changes look pretty dubious too, although some seem worthwhile. OK, that last part seems kind of vague. ;-) Can you hack up the diff to have just the changes you think are worthwhile? You can just remove the parts of the diff you don't like. -- Bruce Momjian br...@momjian.ushttp://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
Bruce Momjian wrote: Robert Haas wrote: On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian br...@momjian.us wrote: The attached patch is a collection of libpq documentation cleanups recommended in a list of changes emailed to me by Leslie S Satenstein. Leslie found a number of places our libpq documentation that were unclear or awkward, and this diff generated by me attempts to address them. I have already updated the documentation proofreading wiki: ? ? ? ?http://wiki.postgresql.org/wiki/Documentation_Proofreading I don't think changing see below to refer below or call to execute is an improvement; even if we did that uniformly throughout our documentation, surely future editors are going to reuse those phrasings. A lot of these other changes look pretty dubious too, although some seem worthwhile. OK, that last part seems kind of vague. ;-) Can you hack up the diff to have just the changes you think are worthwhile? You can just remove the parts of the diff you don't like. Robert, here is a unified diff, which I think it easier to review for single-line documention changes. -- Bruce Momjian br...@momjian.ushttp://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + /pgpatches/libpq.gz Description: GNU Zip compressed data -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
On Wed, Jan 12, 2011 at 1:12 PM, Bruce Momjian br...@momjian.us wrote: OK, that last part seems kind of vague. ;-) Can you hack up the diff to have just the changes you think are worthwhile? You can just remove the parts of the diff you don't like. Robert, here is a unified diff, which I think it easier to review for single-line documention changes. Here are the parts that seem like improvements to me. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company libpq-docs.patch Description: Binary data -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
On ons, 2011-01-12 at 12:04 -0500, Robert Haas wrote: On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian br...@momjian.us wrote: The attached patch is a collection of libpq documentation cleanups recommended in a list of changes emailed to me by Leslie S Satenstein. Leslie found a number of places our libpq documentation that were unclear or awkward, and this diff generated by me attempts to address them. I have already updated the documentation proofreading wiki: http://wiki.postgresql.org/wiki/Documentation_Proofreading I don't think changing see below to refer below or call to execute is an improvement; even if we did that uniformly throughout our documentation, surely future editors are going to reuse those phrasings. Agreed. A lot of these other changes look pretty dubious too, although some seem worthwhile. Agreed. :-/ -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] libpq documentation cleanups (repost 3)
Robert Haas wrote: On Wed, Jan 12, 2011 at 1:12 PM, Bruce Momjian br...@momjian.us wrote: OK, that last part seems kind of vague. ?;-) ?Can you hack up the diff to have just the changes you think are worthwhile? ?You can just remove the parts of the diff you don't like. Robert, here is a unified diff, which I think it easier to review for single-line documention changes. Here are the parts that seem like improvements to me. Applied. I am also attaching a few more of Leslie's changes that I think are useful. The first clarifies a confusion Leslie had about the fact that return is referencing the return value of the function and not the value returned in the pointer. The second change is, I think, better wording. The third moves the deprecated text to the start of the function description. Leslie pointed out that that is how we do it for other libpq functions, so we should move it for consistency. -- Bruce Momjian br...@momjian.ushttp://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index da7b820..335b148 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -972,8 +972,8 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); If literalerrmsg/ is not symbolNULL/, then literal*errmsg/ is set to symbolNULL/ on success, else to a functionmalloc/'d error string explaining the problem. (It is also possible for literal*errmsg/ to be - set to symbolNULL/ even when symbolNULL/ is returned; this indicates an out-of-memory - situation.) + set to symbolNULL/ even when symbolNULL/ is returned by + the function; this indicates an out-of-memory situation.) /para para @@ -1352,7 +1352,7 @@ ConnStatusType PQstatus(const PGconn *conn); para See the entry for functionPQconnectStartParams/, functionPQconnectStart/ and functionPQconnectPoll/ with regards to other status codes that - might be seen. + might be returned. /para /listitem /varlistentry @@ -3162,6 +3162,11 @@ Oid PQoidValue(const PGresult *res); listitem para + This function is deprecated in favor of + functionPQoidValue/function. It is not thread-safe. + /para + + para Returns a string with the OID of the inserted row, if the acronymSQL/acronym command was an commandINSERT/command that inserted exactly one row, or a commandEXECUTE/command of @@ -3175,10 +3180,6 @@ char *PQoidStatus(const PGresult *res); /synopsis /para - para - This function is deprecated in favor of - functionPQoidValue/function. It is not thread-safe. - /para /listitem /varlistentry /variablelist -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
[HACKERS] libpq++ documentation ...
That's one thing that I can't touch, since I have no idea about SGML :( Bruce, can you extract that and add it to the CVS repository for libpq++? ---(end of broadcast)--- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [HACKERS] libpq++ documentation ...
I can remove it cleanly, but I have no idea how to add the SGML in a way that will allow it to build. --- Marc G. Fournier wrote: That's one thing that I can't touch, since I have no idea about SGML :( Bruce, can you extract that and add it to the CVS repository for libpq++? ---(end of broadcast)--- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 6: Have you searched our list archives? http://archives.postgresql.org
Re: [HACKERS] libpq++ documentation ...
On Wed, 21 Aug 2002, Bruce Momjian wrote: I can remove it cleanly, but I have no idea how to add the SGML in a way that will allow it to build. Anyone with some time on their hands that knows SGML enough to do this? :) For now, can you extract what is required and commit it to the project *but* don't remove from our central source(s)? Maybe add a prominent comment in the docs for now that the source has moved to GBorg, so that ppl aren't confused that the docs are there but there is no code, until we can get a 'clean build' of the docs in the project itself? --- Marc G. Fournier wrote: That's one thing that I can't touch, since I have no idea about SGML :( Bruce, can you extract that and add it to the CVS repository for libpq++? ---(end of broadcast)--- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 2: you can get off all lists at once with the unregister command (send unregister YourEmailAddressHere to [EMAIL PROTECTED])
Re: [HACKERS] libpq++ documentation ...
I will remove it from our cvs and move it over, and clean up our SGML to compile properly. I can do that much. --- Marc G. Fournier wrote: On Wed, 21 Aug 2002, Bruce Momjian wrote: I can remove it cleanly, but I have no idea how to add the SGML in a way that will allow it to build. Anyone with some time on their hands that knows SGML enough to do this? :) For now, can you extract what is required and commit it to the project *but* don't remove from our central source(s)? Maybe add a prominent comment in the docs for now that the source has moved to GBorg, so that ppl aren't confused that the docs are there but there is no code, until we can get a 'clean build' of the docs in the project itself? --- Marc G. Fournier wrote: That's one thing that I can't touch, since I have no idea about SGML :( Bruce, can you extract that and add it to the CVS repository for libpq++? ---(end of broadcast)--- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 4: Don't 'kill -9' the postmaster
Re: [HACKERS] libpq++ documentation ...
Done. --- Bruce Momjian wrote: I will remove it from our cvs and move it over, and clean up our SGML to compile properly. I can do that much. --- Marc G. Fournier wrote: On Wed, 21 Aug 2002, Bruce Momjian wrote: I can remove it cleanly, but I have no idea how to add the SGML in a way that will allow it to build. Anyone with some time on their hands that knows SGML enough to do this? :) For now, can you extract what is required and commit it to the project *but* don't remove from our central source(s)? Maybe add a prominent comment in the docs for now that the source has moved to GBorg, so that ppl aren't confused that the docs are there but there is no code, until we can get a 'clean build' of the docs in the project itself? --- Marc G. Fournier wrote: That's one thing that I can't touch, since I have no idea about SGML :( Bruce, can you extract that and add it to the CVS repository for libpq++? ---(end of broadcast)--- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 4: Don't 'kill -9' the postmaster -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 4: Don't 'kill -9' the postmaster
Re: [HACKERS] libpq++ documentation ...
I knew that was coming. Some have been concerned that though Edmund said OK, there is some new person who is the maintainer, though you would think Edmund would be the final word on that. Anyway, I will do it now, or as soon as I empty the patch queue. --- Marc G. Fournier wrote: 'K, wanna do DBD::Pg next? :) On Wed, 21 Aug 2002, Bruce Momjian wrote: Done. --- Bruce Momjian wrote: I will remove it from our cvs and move it over, and clean up our SGML to compile properly. I can do that much. --- Marc G. Fournier wrote: On Wed, 21 Aug 2002, Bruce Momjian wrote: I can remove it cleanly, but I have no idea how to add the SGML in a way that will allow it to build. Anyone with some time on their hands that knows SGML enough to do this? :) For now, can you extract what is required and commit it to the project *but* don't remove from our central source(s)? Maybe add a prominent comment in the docs for now that the source has moved to GBorg, so that ppl aren't confused that the docs are there but there is no code, until we can get a 'clean build' of the docs in the project itself? --- Marc G. Fournier wrote: That's one thing that I can't touch, since I have no idea about SGML :( Bruce, can you extract that and add it to the CVS repository for libpq++? ---(end of broadcast)--- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 4: Don't 'kill -9' the postmaster -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 5: Have you checked our extensive FAQ? http://www.postgresql.org/users-lounge/docs/faq.html
Re: [HACKERS] libpq++ documentation ...
On Wed, 21 Aug 2002, Bruce Momjian wrote: I knew that was coming. Some have been concerned that though Edmund said OK, there is some new person who is the maintainer, though you would think Edmund would be the final word on that. Anyway, I will do it now, or as soon as I empty the patch queue. IMHO, if there is someone else, they should be step'ng forward to let us know, no? ---(end of broadcast)--- TIP 5: Have you checked our extensive FAQ? http://www.postgresql.org/users-lounge/docs/faq.html
Re: [HACKERS] libpq++ documentation ...
Yep, let's create the project. --- Marc G. Fournier wrote: On Wed, 21 Aug 2002, Bruce Momjian wrote: I knew that was coming. Some have been concerned that though Edmund said OK, there is some new person who is the maintainer, though you would think Edmund would be the final word on that. Anyway, I will do it now, or as soon as I empty the patch queue. IMHO, if there is someone else, they should be step'ng forward to let us know, no? -- Bruce Momjian| http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup.| Newtown Square, Pennsylvania 19073 ---(end of broadcast)--- TIP 6: Have you searched our list archives? http://archives.postgresql.org
