Re: Minor improvement in lock.sgml

Here is a patch to a bit improve the reference page for the LOCK
command. I think it'd be better for the isolation level to be in
capitals and wrapped in the <literal> tags.

Thanks,

Best regards,
Etsuro Fujita

On Tue, Sep 16, 2014 at 7:20 AM, Etsuro Fujita
<fujita(dot)etsuro(at)lab(dot)ntt(dot)co(dot)jp> wrote:
> Here is a patch to a bit improve the reference page for the LOCK
> command. I think it'd be better for the isolation level to be in
> capitals and wrapped in the <literal> tags.

It's done that way elsewhere in the same page, so committed.

Overall, there is some ambiguity about this. Most places follow your
proposed style if <literal>READ COMMITTED</literal>,
<literal>REPEATABLE READ</literal>, and
<literal>SERIALIZABLE</literal>, but mvcc.sgml, which discusses
isolation levels extensively, just writes them as Read Committed,
Repeatable Read, and Serializable.

I'm not sure whether more consistency overall would be a good thing -
there are some things to recommend the current mix of styles - but
mixing styles within a page doesn't seem smart, so this much at least
seems uncontroversial.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas wrote:
> On Tue, Sep 16, 2014 at 7:20 AM, Etsuro Fujita
> <fujita(dot)etsuro(at)lab(dot)ntt(dot)co(dot)jp> wrote:
> > Here is a patch to a bit improve the reference page for the LOCK
> > command. I think it'd be better for the isolation level to be in
> > capitals and wrapped in the <literal> tags.
>
> It's done that way elsewhere in the same page, so committed.
>
> Overall, there is some ambiguity about this. Most places follow your
> proposed style if <literal>READ COMMITTED</literal>,
> <literal>REPEATABLE READ</literal>, and
> <literal>SERIALIZABLE</literal>, but mvcc.sgml, which discusses
> isolation levels extensively, just writes them as Read Committed,
> Repeatable Read, and Serializable.

This use of initial capitals everywhere in the mvcc chapter looks
strange to me. I would say that that text needs to use <firstterm>,
like we do elsewhere for terms being explained; and subsequent usage of
the same terms would use them without any particular markup and in
lowercase. For instance, one paragraph there would be:

<para>
The <acronym>SQL</acronym> standard defines four levels of
transaction isolation. The most strict is <firstterm>serializable</>,
which is defined by the standard in a paragraph which says that any
concurrent execution of a set of serializable transactions is guaranteed
to produce the same effect as running them one at a time in some order.
The other three levels are defined in terms of phenomena, resulting from
interaction between concurrent transactions, which must not occur at
each level. The standard notes that due to the definition of
serializable, ...

and there's a later one that would look like

<para>
In <productname>PostgreSQL</productname>, you can request any of the
four standard transaction isolation levels. But internally, there are
only three distinct isolation levels, which correspond to the levels
<firstterm>read committed</>, <firstterm>repeatable read</>, and the
aforementioned serializable. When you select the level <firstterm>read
uncommitted</> you really get read committed, and phantom reads are not possible
in the <productname>PostgreSQL</productname> implementation of repeatable
read, so ...

Maybe there's additional markup of the isolation level names to be had
in appearances other than the first, but I don't know what -- initial
capitals don't seem to cut it. Maybe we should say "the level foo" as
appropriate (so the last line above would be "implementation of the
level repeatable read")

CLP$10

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services