Grammar and formatting errors for 9.02 pdf version

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 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?

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:

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

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