Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lj2YD-00024x-2t for pgsql-docs@arkaria.postgresql.org; Tue, 18 May 2021 16:26:33 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1lj2YC-00079k-0y for pgsql-docs@arkaria.postgresql.org; Tue, 18 May 2021 16:26:32 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lj2YB-00079c-Pj for pgsql-docs@lists.postgresql.org; Tue, 18 May 2021 16:26:31 +0000 Received: from mail-pj1-x102d.google.com ([2607:f8b0:4864:20::102d]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1lj2Y8-0006Ix-7K for pgsql-docs@lists.postgresql.org; Tue, 18 May 2021 16:26:30 +0000 Received: by mail-pj1-x102d.google.com with SMTP id cu11-20020a17090afa8bb029015d5d5d2175so1840009pjb.3 for ; Tue, 18 May 2021 09:26:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yugabyte.com; s=google; h=from:message-id:mime-version:subject:date:in-reply-to:cc:to :references; bh=oApDRnS+wBp45HipGnahXD8oltID+9oMh2Ctv6b3Q4c=; b=ckX82oVk0W2e2l0k/HNKtthElSvL7n4ufHAlT6R5xZ8gRpSnHnR5a4KV9Zae+K0Mb6 AAnU9NHbHtMLfq9TnrH631zFbViNiV04m069N2m1hI6K68TiT0N6KnzQcofV7031OqKH I4NVVmzfBKbVJZyoxOYQXDO11z+0PK2oN4mjA= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:message-id:mime-version:subject:date :in-reply-to:cc:to:references; bh=oApDRnS+wBp45HipGnahXD8oltID+9oMh2Ctv6b3Q4c=; b=jKwDMv1/xMjkWZK/Zvc1Ksv6fJkXklIcCG/O5BEiGwLg+LqhqoOL4KveS+valj43Ux dbXyI48od4Yr921SHHBLOpYEiwp+kqApf/INXfQqbi59nOQ6K4XAurolAveVidPLCOQ1 TuOjPG/ScmIe3ZipPijUtLZWo1DoYwQWUSinV3he4GpwhfkUMZS9AHw8PdvXWG+krh+B TeqGhxoWZda/rdEOfPWt0T306JQ8qCDfNg8cDXsbOYiFAGdUL+XekMGP6uZ7XL6vr7lE K16XebB+ZZj1p3ejgowEG0Pa9c3Gs/9TultgDvHZZ0QEqoFC18r6hzSixqYya0F2CCpe QMcA== X-Gm-Message-State: AOAM532jPQN3jcW5vnqLCtWOFj2bwGWJEjYmj4d6KBaAjnnTDAaisdd/ n+RD+cpubrcRlNNF8kOZcUYZyw== X-Google-Smtp-Source: ABdhPJwjMVLejO1xh/JeTjxddJuSF8nGYZc47Z5o1o8Up9jiA+1pJd+Gq1PsGCo6yFopEWWO2ZBkCA== X-Received: by 2002:a17:902:820b:b029:ef:4c29:2950 with SMTP id x11-20020a170902820bb02900ef4c292950mr5521581pln.78.1621355187027; Tue, 18 May 2021 09:26:27 -0700 (PDT) Received: from smtpclient.apple ([2601:646:101:7fda:2520:d782:433c:898e]) by smtp.gmail.com with ESMTPSA id 3sm12219759pff.132.2021.05.18.09.26.26 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 18 May 2021 09:26:26 -0700 (PDT) From: Bryn Llewellyn Message-Id: <9DB04117-830D-4261-B7DD-E09364ED8DA0@yugabyte.com> Content-Type: multipart/alternative; boundary="Apple-Mail=_6EB8BFC5-EAB6-49BF-A856-492C1744A4B5" Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.80.0.2.43\)) Subject: Re: typo in doc for "Miscellaneous Coding Conventions" Date: Tue, 18 May 2021 09:26:25 -0700 In-Reply-To: <3079730.1621345947@sss.pgh.pa.us> Cc: Pg Docs To: Tom Lane PostgreSQL , tanghy.fnst@fujitsu.com References: <162131484867.24518.3990274826700661694@wrigleys.postgresql.org> <3079730.1621345947@sss.pgh.pa.us> X-Mailer: Apple Mail (2.3654.80.0.2.43) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --Apple-Mail=_6EB8BFC5-EAB6-49BF-A856-492C1744A4B5 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 tgl@sss.pgh.pa.us wrote: > PG Doc comments form writes: >=20 >> small fix in description at [1] as follows >=20 >> -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. >=20 > 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) =E2=80=9CIF bla bla=E2=80=A6 THEN bla bla=E2=80=A6=E2=80=9D 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 (=E2=80=9Cmistakes = were made=E2=80=9D). 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=E2=80=99t do X, then Y bad thing = could happen.= --Apple-Mail=_6EB8BFC5-EAB6-49BF-A856-492C1744A4B5 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8 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) =E2=80=9CIF bla bla=E2=80=A6 = <comma> THEN bla bla=E2=80=A6=E2=80=9D

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 (=E2=80=9Cmistakes were made=E2=80=9D). 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=E2=80=99t do X, then = Y bad thing could happen.
= --Apple-Mail=_6EB8BFC5-EAB6-49BF-A856-492C1744A4B5--