Re: [PATCH] Docs: Make notes on sequences and rollback more obvious

On Sat, Aug 4, 2012 at 12:56 AM, Craig Ringer <ringerc(at)ringerc(dot)id(dot)au> wrote:
> On 08/04/2012 04:12 AM, Kevin Grittner wrote:
>> I haven't reviewed it in detail but noticed an apparent editing error:
>> "which are used the counters" should probably have an "as" thrown in there.
>> Or something.
>
> Thanks. Editing fail. I revised that spot repeatedly to try to keep it short
> and simple without in any way implying that SEQUENCEs are *only* used for
> SERIAL columns.
>
> Fixed attached.

In datatype.sgml, I think that adding that <important> block in the
middle of the existing paragraph is too choppy. I moved it down a
bit, changed it to a note, expanded it a little, and fixed some typos
and markup.

In func.sgml, I chose to keep the <important> at the end, instead of
switching the order of the paragraphs as you did, but I moved it up
under nextval instead of having it at the end, as you had it. I kept
your note in setval() but cleaned it up a bit.

I did not commit the advanced.sgml changes. I am not sure I believe
the assertion that any function or type with special transactional
behavior will include a documentation mention. It doesn't seem like a
terribly future-proof assertion at any rate. With respect to the
mention of autocommit, I think it would be good to add something
there, but maybe it should cross-reference our existing documentation
mentions of autocommit. Also, it's a bit ambiguous the way it's
worded whether you get the automatic BEGIN/COMMIT with autocommit=on
or with autocommit=off; somehow we should try to clarify what we mean
a little more there.

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