diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index c528010723b..172345e412a 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
@@ -818,6 +818,38 @@ FOR UPDATE [ OF table_name [, ...]
rows; for example it can't be used with aggregation.
+
+ FOR UPDATE may appear before
+ LIMIT for compatibility with
+ PostgreSQL versions before 7.3. It
+ effectively executes after LIMIT, however, and
+ so that is the recommended place to write it.
+
+
+
+
+ Avoid locking a row and then modifying it within a later savepoint or
+ PL/pgSQL exception block. A subsequent
+ rollback would cause the lock to be lost. For example,
+
+BEGIN;
+SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
+SAVEPOINT s;
+UPDATE mytable SET ... WHERE key = 1;
+ROLLBACK TO s;
+
+ After the ROLLBACK, the row is effectively unlocked, rather
+ than returned to its pre-savepoint state of being locked but not modified.
+ This hazard occurs if a row locked in the current transaction is updated
+ or deleted: the former lock state is forgotten. If the transaction is then
+ rolled back to a state between the original locking command and the
+ subsequent change, the row will appear not to be locked at all. This is
+ an implementation deficiency which will be addressed in a future release
+ of PostgreSQL.
+
+
+
+
It is possible for a SELECT command using both
LIMIT and FOR UPDATE
@@ -827,14 +859,7 @@ FOR UPDATE [ OF table_name [, ...]
Once the SELECT unblocks, the query qualification might not
be met and the row not be returned by SELECT.
-
-
- FOR UPDATE may appear before
- LIMIT for compatibility with
- PostgreSQL versions before 7.3. It
- effectively executes after LIMIT, however, and
- so that is the recommended place to write it.
-
+