Обсуждение: Grammar and formatting errors for 9.02 pdf version

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