Re: typo in doc for "Miscellaneous Coding Conventions" - Mailing list pgsql-docs

From Bryn Llewellyn
Subject Re: typo in doc for "Miscellaneous Coding Conventions"
Date
Msg-id 9DB04117-830D-4261-B7DD-E09364ED8DA0@yugabyte.com
Whole thread Raw
In response to Re: typo in doc for "Miscellaneous Coding Conventions"  (Tom Lane <tgl@sss.pgh.pa.us>)
Responses RE: typo in doc for "Miscellaneous Coding Conventions"  ("tanghy.fnst@fujitsu.com" <tanghy.fnst@fujitsu.com>)
List pgsql-docs
tgl@sss.pgh.pa.us wrote:

PG Doc comments form  writes:

small fix in description at [1] as follows

-If that were not done interrupted code that's currently inspecting errno
might see the wrong value.
+If that was not done interrupted code that's currently inspecting errno
might see the wrong value.

The existing text is perfectly good English; your change
makes it less so.  I'm afraid it's been too many years since
high school English for me to remember the exact grammatical
term for this, but "were not" is typical usage when stating
a contrary-to-fact hypothetical.

(1) “IF bla bla… <comma> THEN bla bla…”

It might be more words than the bare minimum. But it helps the user separate out the proposition and the consequence.

(2) This is the dreaded curse of the passive voice (“mistakes were made”). There are many cases where an active formulation is nicer. Anyway, you can sidestep lots of the conundrums, like the alternatives here pose, by standing back and finding a different way to make the point.

> If the implementation (or you) didn’t do X, then Y bad thing could happen.

pgsql-docs by date:

Previous
From: Tom Lane
Date:
Subject: Re: typo in doc for "Miscellaneous Coding Conventions"
Next
From: Laurenz Albe
Date:
Subject: Improve documentation for pg_upgrade, standbys and rsync