public inbox for [email protected]
help / color / mirror / Atom feedMake default values bold in Synopsis / bnf diagram
3+ messages / 3 participants
[nested] [flat]
* Make default values bold in Synopsis / bnf diagram
@ 2019-12-02 21:19 PG Doc comments form <[email protected]>
2019-12-20 20:56 ` Re: Make default values bold in Synopsis / bnf diagram Bruce Momjian <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: PG Doc comments form @ 2019-12-02 21:19 UTC (permalink / raw)
To: [email protected]; +Cc: [email protected]
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/sql-set-transaction.html
Description:
As an example let's take take "BEGIN"
in the Synopsis :
-------- Start Synopsis for BEGIN --------------------
BEGIN [ WORK | TRANSACTION ] [ transaction_mode [, ...] ]
where transaction_mode is one of:
ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ
UNCOMMITTED }
READ WRITE | READ ONLY
[ NOT ] DEFERRABLE
-------- End Synopsis for BEGIN --------------------
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.
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".
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Make default values bold in Synopsis / bnf diagram
2019-12-02 21:19 Make default values bold in Synopsis / bnf diagram PG Doc comments form <[email protected]>
@ 2019-12-20 20:56 ` Bruce Momjian <[email protected]>
2019-12-20 21:18 ` Re: Make default values bold in Synopsis / bnf diagram David G. Johnston <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Bruce Momjian @ 2019-12-20 20:56 UTC (permalink / raw)
To: [email protected]; [email protected]
On Mon, Dec 2, 2019 at 09:19:32PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/sql-set-transaction.html
> Description:
>
> As an example let's take take "BEGIN"
> in the Synopsis :
> -------- Start Synopsis for BEGIN --------------------
> BEGIN [ WORK | TRANSACTION ] [ transaction_mode [, ...] ]
>
> where transaction_mode is one of:
>
> ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ
> UNCOMMITTED }
> READ WRITE | READ ONLY
> [ NOT ] DEFERRABLE
> -------- End Synopsis for BEGIN --------------------
> 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.
> 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?
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Make default values bold in Synopsis / bnf diagram
2019-12-02 21:19 Make default values bold in Synopsis / bnf diagram PG Doc comments form <[email protected]>
2019-12-20 20:56 ` Re: Make default values bold in Synopsis / bnf diagram Bruce Momjian <[email protected]>
@ 2019-12-20 21:18 ` David G. Johnston <[email protected]>
0 siblings, 0 replies; 3+ messages in thread
From: David G. Johnston @ 2019-12-20 21:18 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: [email protected]; [email protected]
On Fri, Dec 20, 2019 at 1:56 PM Bruce Momjian <[email protected]> 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 <em class="default"> 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.
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2019-12-20 21:18 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-12-02 21:19 Make default values bold in Synopsis / bnf diagram PG Doc comments form <[email protected]>
2019-12-20 20:56 ` Bruce Momjian <[email protected]>
2019-12-20 21:18 ` David G. Johnston <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox