Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1iiPfV-0002if-3F for pgsql-docs@arkaria.postgresql.org; Fri, 20 Dec 2019 21:18:41 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1iiPfT-0001PH-Ko for pgsql-docs@arkaria.postgresql.org; Fri, 20 Dec 2019 21:18:39 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1iiPfT-0001PA-76 for pgsql-docs@lists.postgresql.org; Fri, 20 Dec 2019 21:18:39 +0000 Received: from mail-qk1-x729.google.com ([2607:f8b0:4864:20::729]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1iiPfQ-000288-RC for pgsql-docs@lists.postgresql.org; Fri, 20 Dec 2019 21:18:38 +0000 Received: by mail-qk1-x729.google.com with SMTP id r14so8755600qke.13 for ; Fri, 20 Dec 2019 13:18:36 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=M+lSuTLQXLYEcVQsaH3hav1OYIvhMXDz3z4Se5xEyVc=; b=LjqYRSKgYoUxVr6QomB+mCLIWYkcsc7dMSniGEoAvlkXcBNJizdZRNnN9PwtHYD/bb /yyk7CBRRNJ7mWhqD2d3PwXgJySz3ePXTXsR6Wap/lWWdX76daToNL+CZMunmQJt6Jej Jppym0sZyXWdZCbJBh4E4HjatINfMK2icAHuH6PpOldmlJSnISlk5EuiERS9V8gwEM3o Rz9vedPXZsuYgYBk6WVByCDHQXUcFfzWpKlTSxDEfFBTkyY1f9y9Gk+B/4ALjI8j3M+R eWrMR5X2NEdzzaUvQL8lD+yiO5oJjn+vxDJnGO8DcYQslhxFofGijXxWR/+ysB7G77Gr PatQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=M+lSuTLQXLYEcVQsaH3hav1OYIvhMXDz3z4Se5xEyVc=; b=KDxXg2ZRE44MTWwYj8q0KCPrATcqZZeEFDxCVo/YHWFb2JB4PTAiFvPfP5oUVGxuQJ NpNx1mwsXT0VkwF2GguzxqhLpO5NEdDhWLvh7mXLb5Ca1jG8Lmw/ql4DKYziEoIlpyoI bs9xomRnp712ZbcooYgqWFywCbBl2yoxG5rHFhH6PutNYvkcKwrb51IVh7tBf+E5FKVU NCZMf4DG4OCRN29hBxRBscad3yVvLXsl5Yac55HyQ0NFOAs47W3fJBuXpJaQaLmoSmtO FSzftHbEhEdU/3I0a6Yi6/JMP2cR16Ouzg9gLqDXzaaCMeLYWFUgAWJ2AC0HSwLIzBRC lYXg== X-Gm-Message-State: APjAAAWNaiCDelxt8xQ5KhGsLziFlB4RQaR44APb2dzo3TvVT1PUBmg1 8CjIG0d8iGltoo28x2O3EbNXoq2t5D3XB/CR6PY= X-Google-Smtp-Source: APXvYqz19fIS9Eh2WnzDlxKKGgg2kaGiDx5touUsSZXM/9BPFJ5KMRWAG9joHiHk7wsv1/qbcqsEgSulJTFURoMxr6w= X-Received: by 2002:a37:9a58:: with SMTP id c85mr15391079qke.478.1576876715665; Fri, 20 Dec 2019 13:18:35 -0800 (PST) MIME-Version: 1.0 References: <157532157256.21496.16702798757154104275@wrigleys.postgresql.org> <20191220205622.GG29807@momjian.us> In-Reply-To: <20191220205622.GG29807@momjian.us> From: "David G. Johnston" Date: Fri, 20 Dec 2019 14:18:18 -0700 Message-ID: Subject: Re: Make default values bold in Synopsis / bnf diagram To: Bruce Momjian Cc: peter.m.gram@gmail.com, pgsql-docs@lists.postgresql.org Content-Type: multipart/alternative; boundary="0000000000007deba1059a2938bb" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --0000000000007deba1059a2938bb Content-Type: text/plain; charset="UTF-8" On Fri, Dec 20, 2019 at 1:56 PM Bruce Momjian wrote: > On Mon, Dec 2, 2019 at 09:19:32PM +0000, PG Doc comments form wrote: > > > In this example the words to words "READ COMMITTED", "READ WRITE" should > be > > bold since they are default values if I execute the statement "BEGIN;" > see > > the example. > > Uh, I don't think we bold the defaults in the syntax, but if we wanted > to do that, we should do it everywhere. Is that something we want? I > am afraid it would just make the default values stand out, which seems > counter-productive. > I originally agreed with theoretically adding to these but further evaluation below lessens its utility. > By the way I started in "BEGIN" but here the defaults was not even present > > sow I went to "START TRANSACTION but still no indication on default > values > > but finally in "SET TRANSACTION" > > There are default value for "ISOLATION LEVEL" but nothing on default > value > > for "READ WRITE | READ ONLY" or "[ NOT ] DEFERRABLE". > > Uh, I see in the BEGIN manual page: > > If the isolation level, read/write mode, or deferrable mode is > specified, the new transaction has those characteristics, as if SET > TRANSACTION (SET_TRANSACTION(7)) was executed. > > and in SET TRANSACTION: > > If the isolation level, read/write mode, or deferrable mode is > specified, the new transaction has those characteristics, as if SET > TRANSACTION (SET_TRANSACTION(7)) was executed. > > Is "has those characteristics" unclear? > > The OP is complaining about the "is not specified" situation. One complication here, which is noted on the SET TRANSACTION page, is: "The session default transaction modes can also be set by setting the configuration parameters default_transaction_isolation, default_transaction_read_only, and default_transaction_deferrable." So in fact the defaults we'd be highlighting would only be the ones that are shipped since the execution environment may have different defaults. My take-away is that while the OP may have a valid gripe regarding the documentation and how it presents transactions - learning about the defaults and how to change them - the proposed solution is neither particularly practical nor desirable given that what is default is not something that can be absolutely documented. It is obvious that transactions are not read only by default and defer-ability seldom comes up and in learning about it one does learn its typical default (not deferred). And there are numerous references when learning about transaction isolation that the shipped default is read committed. I don't see this single instance of confusion as a call for the developers to go find a better way to write/organize the documentation. Specific suggestions are welcome though this one I would say should be turned down. David J. --0000000000007deba1059a2938bb Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Fri, Dec 20, 2019 at 1:56 PM Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Dec=C2=A0 2, 2019 at 09:19:32PM +0000, PG Doc comments f= orm wrote:

> In this example the words to words "READ COMMITTED", "R= EAD WRITE" should be
> bold since they are default values if I execute the statement "BE= GIN;" see
> the example.

Uh, I don't think we bold the defaults in the syntax, but if we wanted<= br> to do that, we should do it everywhere.=C2=A0 Is that something we want?=C2= =A0 I
am afraid it would just make the default values stand out, which seems
counter-productive.

I originally agr= eed with theoretically adding <em class=3D"default"> to the= se but further evaluation below lessens its utility.

> By the way I started in "BEGIN" but here the defaults was no= t even present
> sow I went to "START TRANSACTION but still no indication on defau= lt values
> but finally in "SET TRANSACTION"
> There are default value for "ISOLATION LEVEL" but nothing on= default value
> for "READ WRITE | READ ONLY" or=C2=A0 "[ NOT ] DEFERRAB= LE".

Uh, I see in the BEGIN manual page:

=C2=A0 =C2=A0 =C2=A0 =C2=A0 If the isolation level, read/write mode, or def= errable mode is
=C2=A0 =C2=A0 =C2=A0 =C2=A0 specified, the new transaction has those charac= teristics, as if SET
=C2=A0 =C2=A0 =C2=A0 =C2=A0 TRANSACTION (SET_TRANSACTION(7)) was executed.<= br>
and in SET TRANSACTION:

=C2=A0 =C2=A0 =C2=A0 =C2=A0 If the isolation level, read/write mode, or def= errable mode is
=C2=A0 =C2=A0 =C2=A0 =C2=A0 specified, the new transaction has those charac= teristics, as if SET
=C2=A0 =C2=A0 =C2=A0 =C2=A0 TRANSACTION (SET_TRANSACTION(7)) was executed.<= br>
Is "has those characteristics" unclear?

=
The OP is complaining about the "is not specified" s= ituation.

One complication here, which is noted on the= SET TRANSACTION page, is:

"The session default t= ransaction modes can also be set by setting the configuration parameters de= fault_transaction_isolation, default_transaction_read_only, and default_tra= nsaction_deferrable."

So in fact the defaults= we'd be highlighting would only be the ones that are shipped since the= execution environment may have different defaults.

My= take-away is that while the OP may have a valid gripe regarding the docume= ntation and how it presents transactions - learning about the defaults and = how to change them - the proposed solution is neither particularly practica= l nor desirable given that what is default is not something that can be abs= olutely documented.

It is obvious that transactions ar= e not read only by default and defer-ability seldom comes up and in learnin= g about it one does learn its typical default (not deferred).=C2=A0 And the= re are numerous references when learning about transaction isolation that t= he shipped default is read committed.=C2=A0 I don't see this single ins= tance of confusion as a call for the developers to go find a better way to = write/organize the documentation.=C2=A0 Specific suggestions are welcome th= ough this one I would say should be turned down.

David= J.

--0000000000007deba1059a2938bb--