Thread: Grammar and formatting errors for 9.02 pdf version

Grammar and formatting errors for 9.02 pdf version

From
Leslie S Satenstein
Date:
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

Re: Grammar and formatting errors for 9.02 pdf version

From
Robert Haas
Date:
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

Re: Grammar and formatting errors for 9.02 pdf version

From
Robert Haas
Date:
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

Re: Grammar and formatting errors for 9.02 pdf version

From
Alvaro Herrera
Date:
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

Re: Grammar and formatting errors for 9.02 pdf version

From
Leslie S Satenstein
Date:

--- On Tue, 12/21/10, Robert Haas <robertmhaas@gmail.com> wrote:

From: Robert Haas <robertmhaas@gmail.com>
Subject: Re: [DOCS] Grammar and formatting errors for 9.02 pdf version
To: "Leslie S Satenstein" <lsatenstein@yahoo.com>
Cc: "pgsql-docs" <pgsql-docs@postgresql.org>
Date: Tuesday, December 21, 2010, 10:56 PM

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 and yellow for elaboration or comments.  And of course, as well, to identify the page from the pdf guide.
>
> Some text, if rephrased, makes the meaning more clear. Some text has missing nouns and where several nouns precede a pronoun,  it causes a delay as one stops to analyze the sentence in order 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


Hi Robert.
Since Yahoo.com does not allow me to respond as an append, please excuse the formatting that takes place in the left margin.

 
For this time, please use html for reading this email.

Here is an example of how I was thinking to proceed but using a word document so that formatting would be respected.  I would present the page in word, and then identify the changes with red/green.  To keep this email short, I am showing only a very few changes. Green is for an insertion, Red is for a deletion.  Yellow is for clarification

PDF 9.02 Page 591, bottom
tty

Ignored (formerly, this parameter specified where to send server debug output).

Word parameter is inserted.

Page 594
Text below is truncated as it goes beyond the right margin

Make a connection to the database server in a nonblocking manner.
PGconn *PQconnectStartParams(const char **keywords, const char **values, int expand_dbname);
 
Page 595
To begin a nonblocking connection callexecute conn =

Further down

IfAfter PQconnectStart succeeds ...

Leaving the opening If ..... in my mind says, what to do if it does not succeed then what?  By writing after PQConnectStart succeeds... takes away liability.

There is some rewording that I would do on later pages.  Why do I bring these changes up for review, because of Latin readers (French/ Spanish readers are translating the English and therefore good precision is needed). Living in Quebec Canada, and doing business in Latin America, I have become trilingual and write software and documentation in these additional languages.

Oh yes, in this chapter 31, protocol is mentioned several times.  But the very first time protocol is defined or explained is in chapter 46.  I believe that a forward reference is required before the first mention of this property (page 602).

Regards
Bien à vous

Leslie

Re: Grammar and formatting errors for 9.02 pdf version

From
Robert Haas
Date:
On Wed, Dec 22, 2010 at 5:08 PM, Leslie S Satenstein <lsatenstein@yahoo.com> wrote:

--- 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.
 
 Here is an example of how I was thinking to proceed but using a word document so that formatting would be respected.  I would present the page in word, and then identify the changes with red/green.  To keep this email short, I am showing only a very few changes. Green is for an insertion, Red is for a deletion.  Yellow is for clarification

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
Text below is truncated as it goes beyond the right margin


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
conn =

What's wrong with call?
 


Further down

IfAfter PQconnectStart succeeds ...

Leaving the opening If ..... in my mind says, what to do if it does not succeed then what?  By writing after PQConnectStart succeeds... takes away liability.

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