Re: [PATCH] Various documentation typo/grammar fixes

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.  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?page=2

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

Starting a parenthetical clause with "e.g." and ending it with
", etc." also looks wrong to me.  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