Thread: Grammar and formatting errors for 9.02 pdf version
| I have been reviewing the documentation and in particular chapter 31. I found quite a few grammar and formatting errors which make for a lot of head scratching about what to do. Are there any groups working on fixing up the doc? Is there a desire to just leave it as is? ------------------ Regards Leslie Mr. Leslie Satenstein mailto:lsatenstein@yahoo.com mailto leslie.satenstein@itbms.biz / leslies@itbms.biz www.itbms.biz |
On Tue, Dec 21, 2010 at 6:19 PM, Leslie S Satenstein <lsatenstein@yahoo.com> wrote: > I have been reviewing the documentation and in particular chapter 31. I found quite a few grammar and formatting errorswhich make for a lot of head scratching about what to do. > > Are there any groups working on fixing up the doc? Is there a desire to just leave it as is? We're always interested in making improvements to the documentation, and certainly any grammatical errors should be fixed. You'll have to tell us what you think they are, though, or better yet provide a patch. With respect to formatting errors, we tend to worry more about the HTML versions of the docs than the PDF. However, you should certainly point out what you have noticed so that we can try to determine whether anything can be done to improve the situation. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On Tue, Dec 21, 2010 at 10:43 PM, Leslie S Satenstein <lsatenstein@yahoo.com> wrote: > > Hi Robert, I am not familiar with your patch process. However, I can copy and paste the offending lines in the PDF file,to a word or openoffice document, and use green for insert and red text for delete. As well as identifying the page. > > Some text, if rephrased, makes the meaning more clear. Some text has missing nouns and where several nouns preceed a pronoun, it causes a delay as one analyzes the sentence to extract the author's meaning. > > If there is a better way, please advise me. Please keep replies on-list, and write your replies beneath the quoted text rather than above it. To submit a patch, you need to check out the source code, edit the SGML documentation, and then use git diff. See: http://wiki.postgresql.org/wiki/Submitting_a_Patch In short: git clone git://git.postgresql.org/git/postgresql.git <make your changes in doc/src/sgml> git diff > grammar.patch <email the patch file to pgsql-docs> If you have only a handful of changes, feel free to just point out the parts that you think could be phrased better and how you think they should be written, rather than generating a patch. Actually, it'd probably be better to point out the first few changes that way anyhow, to see if we agree with your opinions on what should be done. If you're submitting a large number of edits, you're going to have to learn how to generate a patch file as per the above, because otherwise it's going to be extremely laborious for anyone to think about applying your changes. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Excerpts from Robert Haas's message of mar dic 21 23:33:19 -0300 2010: > With respect to formatting errors, we tend to worry more about the > HTML versions of the docs than the PDF. That said, we have certainly made some changes to the text to better acommodate the PDF output, particularly where program output is too wide to fit the page, which is more common than we'd like. > However, you should certainly > point out what you have noticed so that we can try to determine > whether anything can be done to improve the situation. What Robert said. -- Álvaro Herrera <alvherre@commandprompt.com> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support
--- On Tue, 12/21/10, Robert Haas <robertmhaas@gmail.com> wrote:
|
On Wed, Dec 22, 2010 at 5:08 PM, Leslie S Satenstein <lsatenstein@yahoo.com> wrote:
I very much doubt this is true.
This is just impenetrable. I spent 10 minutes trying to figure out what the first example below referred to.
This is on page 590 in the version of the PDF I downloaded, which surely illustrates the folly of trying to refer to anything by page number. rather than, say, section title. Or, better yet, providing an actual patch. While inserting the word parameter here might marginally more correct, the original text isn't unclear, and I'm certainly not willing to spend a huge amount of time on changes like this. If you're willing to learn how to send a patch, I or someone else will review it and some of your changes might be accepted, but I don't think anyone's going to be willing to be willing to try to interpret anything in this format.
I found this - it does go beyond the right margin. I'm not sure what to do about this one.
What's wrong with call?
If it doesn't succeed then you mustn't do what the rest of the sentence says. The sentence is correct as written and would be wrong with this change. By succeeds what is meant here is "returns non-NULL", as discussed in the preceding paragraph.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
--- On Tue, 12/21/10, Robert Haas <robertmhaas@gmail.com> wrote:Since Yahoo.com does not allow me to respond as an append, please excuse the formatting that takes place in the left margin.
I very much doubt this is true.
This is just impenetrable. I spent 10 minutes trying to figure out what the first example below referred to.
Ignored (formerly, this parameter specified where to send server debug output).
This is on page 590 in the version of the PDF I downloaded, which surely illustrates the folly of trying to refer to anything by page number. rather than, say, section title. Or, better yet, providing an actual patch. While inserting the word parameter here might marginally more correct, the original text isn't unclear, and I'm certainly not willing to spend a huge amount of time on changes like this. If you're willing to learn how to send a patch, I or someone else will review it and some of your changes might be accepted, but I don't think anyone's going to be willing to be willing to try to interpret anything in this format.
Page 594
Make a connection to the database server in a nonblocking manner.
PGconn *PQconnectStartParams(const char **keywords, const char **values, int expand_dbname);
I found this - it does go beyond the right margin. I'm not sure what to do about this one.
Page 595
To begin a nonblocking connection callexecute
What's wrong with call?
Further down
IfAfter PQconnectStart succeeds ...
If it doesn't succeed then you mustn't do what the rest of the sentence says. The sentence is correct as written and would be wrong with this change. By succeeds what is meant here is "returns non-NULL", as discussed in the preceding paragraph.
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company