Обсуждение: 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 <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@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
2011/1/12 Robert Haas <robertmhaas@gmail.com>
On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@momjian.us> wrote:I don't think changing "see below" to "refer below" or "call" to
> 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
"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, 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.
Robert Haas wrote: > On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@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 <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian wrote: > Robert Haas wrote: > > On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@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 <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On Wed, Jan 12, 2011 at 1:12 PM, Bruce Momjian <bruce@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
Вложения
On ons, 2011-01-12 at 12:04 -0500, Robert Haas wrote: > On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@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. :-/
Robert Haas wrote: > On Wed, Jan 12, 2011 at 1:12 PM, Bruce Momjian <bruce@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 <bruce@momjian.us> http://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 <literal>errmsg</> is not <symbol>NULL</>, then <literal>*errmsg</> is set to <symbol>NULL</> on success, else to a <function>malloc</>'d error string explaining the problem. (It is also possible for <literal>*errmsg</> to be - set to <symbol>NULL</> even when <symbol>NULL</> is returned; this indicates an out-of-memory - situation.) + set to <symbol>NULL</> even when <symbol>NULL</> 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 <function>PQconnectStartParams</>, <function>PQconnectStart</> and <function>PQconnectPoll</> 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 + <function>PQoidValue</function>. It is not thread-safe. + </para> + + <para> Returns a string with the OID of the inserted row, if the <acronym>SQL</acronym> command was an <command>INSERT</command> that inserted exactly one row, or a <command>EXECUTE</command> of @@ -3175,10 +3180,6 @@ char *PQoidStatus(const PGresult *res); </synopsis> </para> - <para> - This function is deprecated in favor of - <function>PQoidValue</function>. It is not thread-safe. - </para> </listitem> </varlistentry> </variablelist>
On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <bruce@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
Robert Haas wrote: > On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <bruce@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 <bruce@momjian.us> http://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 <literal>errmsg</> is not <symbol>NULL</>, then <literal>*errmsg</> is set to <symbol>NULL</> on success, else to a <function>malloc</>'d error string explaining the problem. (It is also possible for <literal>*errmsg</> to be - set to <symbol>NULL</> even when <symbol>NULL</> is returned; this indicates an out-of-memory - situation.) + set to <symbol>NULL</> and the function to return <symbol>NULL</>; + this indicates an out-of-memory condition.) </para> <para> @@ -1352,7 +1352,7 @@ ConnStatusType PQstatus(const PGconn *conn); <para> See the entry for <function>PQconnectStartParams</>, <function>PQconnectStart</> and <function>PQconnectPoll</> 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 - <acronym>SQL</acronym> command was an <command>INSERT</command> - that inserted exactly one row, or a <command>EXECUTE</command> of - a prepared statement consisting of a suitable - <command>INSERT</command>. (The string will be <literal>0</> if - the <command>INSERT</command> did not insert exactly one row, or - if the target table does not have OIDs.) If the command was not - an <command>INSERT</command>, returns an empty string. + This function is deprecated in favor of + <function>PQoidValue</function> and is not thread-safe. + It returns a string with the OID of the inserted row, while + <function>PQoidValue</function> returns the OID value. <synopsis> char *PQoidStatus(const PGresult *res); </synopsis> </para> - <para> - This function is deprecated in favor of - <function>PQoidValue</function>. It is not thread-safe. - </para> </listitem> </varlistentry> </variablelist>