References: 
 <CABRT9RA_kHEZrw9W=C_yYpR8+TTLqVMVKUSU0hrLC213cJ4Hyg@mail.gmail.com>
 <1408994031.21717.YahooMailNeo@web122306.mail.ne1.yahoo.com>
 <CABRT9RBDUVXJGoVP3CGL2y5JbpqHSGjH1871wPBj3fw+qX_b3g@mail.gmail.com>
 <1409003998.48777.YahooMailNeo@web122302.mail.ne1.yahoo.com>
 <CABRT9RCR8XziafHjS=P6DvKxQ2x1T=EnmB4MsLBqwf23byDOig@mail.gmail.com>
 <1409416383.3283.YahooMailNeo@web122306.mail.ne1.yahoo.com>
 <6438.1409420606@sss.pgh.pa.us>
 <CABRT9RAVz97XWqpFT+tOSDkiwqJAiHvMHZxNY0hyfETFb_xn5g@mail.gmail.com>
Message-ID: <1409750364.93461.YahooMailNeo@web122305.mail.ne1.yahoo.com>
Date: Wed, 3 Sep 2014 06:19:24 -0700
From: Kevin Grittner <kgrittn@ymail.com>
Reply-To: Kevin Grittner <kgrittn@ymail.com>
Subject: Re: [PATCH] Various documentation typo/grammar fixes
To: Marti Raudsepp <marti@juffo.org>, Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs <pgsql-docs@postgresql.org>
In-Reply-To: 
 <CABRT9RAVz97XWqpFT+tOSDkiwqJAiHvMHZxNY0hyfETFb_xn5g@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

Marti Raudsepp <marti@juffo.org> wrote:
> On Sat, Aug 30, 2014 at 8:43 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> I would argue against applying patch 2 at all.
>
> I don't feel strongly about this, I originally didn't plan to submit
> this patch at all. But I don't agree with:
>
>> doing it only because some style guide tells
>> you to is not the way to approach the issue.=A0 We're writing English
>> not C code here, and so there is no single standard of correctness.
>
> There isn't a "single standard", but there are many style guides
> about
> English and pretty much all of them agree on the usage of periods in
> "e.g.", "i.e.", "etc." and "et al."

To me, omitting the dots in any of those looks like a misspelling.
I think we should fix those.

Also, it seems odd to so strictly enforce formatting rules in C
code (where it makes no semantic difference) but blow off style
issues, and even correctness of English usage, in the
documentation.

> With regards to commas following e.g. and i.e., this article surveyed
> 6 different English style guides and just 1 recommended not using the
>
> comma: http://www.quickanddirtytips.com/education/grammar/ie-versus-eg?pa=
ge=3D2

Commas after "i.e." and "e.g." are less clearly a correctness issue=20
and getting more into style questions, so I wouldn't feel too bad=20
about letting those go where it doesn't cause confusion or too much=20
of a "double take" on reading.=A0 Note that the cited page summarizes=20
the positions of these documents on the topic with phrases like "is=20
usually used", "preferable/optional", "makes good sense", and=20
"should be".=A0 Only "The Columbia Guide to Standard American=20
English" actually said it was "required".

Starting a parenthetical clause with "e.g." and ending it with
", etc." also looks wrong to me.=A0 My inclination is to pick one;
otherwise I find it distracting or confusing and tend to go back
over it one or two extra times to make sure I'm understanding.

There's at least one place I spotted "e.g." where it seemed to me
that the "example" was really a restatement in other terms, so it
seemed like it should have been "i.e." -- I would be inclined to
scan for more of those and present that as a separate patch, since
it's less mechanical than the others.

--
Kevin Grittner
EDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company


--=20
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs