Robert Haas wrote:
> On Tue, Sep 16, 2014 at 7:20 AM, Etsuro Fujita
> <fujita.etsuro@lab.ntt.co.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
ofa 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>readcommitted</>, <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