Some of the transaction news for 3.3a3 was incorrect, and

more was incomprehensible.  Tried to repair that.  Plus
random improvements to ReST markup.

branches/3.3/NEWS.txt

@@ -12,34 +12,38 @@ It was missing the case where the only pending modifications were made
 in subtransactions.  This has been fixed.  If an attempt to close a
 connection with pending subtransactions is made now,
 
-    ConnnectionStateError: Cannot close a connection with a pending subtransaction
+    ``ConnnectionStateError: Cannot close a connection with a pending subtransaction``
 
 is raised.
 
 transaction
 -----------
 
-If ReadConflictError was raised by an attempt to load an object with a
-_p_independent() method that returned false, attempting to commit the
-transaction failed to (re)raise ReadConflictError for that object.  Note
-that ZODB intends to prevent committing a transaction in which a
-ReadConflictError occurred; this was an obscure case it missed.
-
-Growing pains:  ZODB 3.1 and 3.2 had a bug wherein Transaction.begin()
-didn't abort the current transaction if the only pending changes were in a
-subtransaction.  In ZODB 3.3, it's intended that transaction managers be
-used instead of invoking methods directly on Transaction objects, and
-calling begin() on a transaction manager didn't have this old bug.  However,
-Transaction.begin() still exists in 3.3, and it had a worse bug:  it never
-aborted the transaction (not even if changes were pending outside of
-subtransactions).  Transaction.begin() has been changed to abort the
-transaction, although it's still strongly recommended to invoke begin() on
-the relevant transaction manager instead.  For example,
+- Some explanations of new transaction features in the 3.3a3 news
+  were incorrect, and this news file has been retroactively edited to
+  repair that.  See news for 3.3a3 below.
+
+- If ReadConflictError was raised by an attempt to load an object with a
+  ``_p_independent()`` method that returned false, attempting to commit the
+  transaction failed to (re)raise ReadConflictError for that object.  Note
+  that ZODB intends to prevent committing a transaction in which a
+  ReadConflictError occurred; this was an obscure case it missed.
+
+- Growing pains:  ZODB 3.1 and 3.2 had a bug wherein ``Transaction.begin()``
+  didn't abort the current transaction if the only pending changes were in a
+  subtransaction.  In ZODB 3.3, it's intended that transaction managers be
+  used instead of invoking methods directly on Transaction objects, and
+  calling ``begin()`` on a transaction manager didn't have this old bug.
+  However, ``Transaction.begin()`` still exists in 3.3, and it had a worse
+  bug:  it never aborted the transaction (not even if changes were pending
+  outside of subtransactions).  ``Transaction.begin()`` has been changed to
+  abort the transaction, although it's still strongly recommended to invoke
+  ``begin()`` on the relevant transaction manager instead.  For example::
 
     import transaction
     transaction.begin()
 
-if using the default ThreadTransactionManager (see news for 3.3a3 below).
+  if using the default ThreadTransactionManager (see news for 3.3a3 below).
 
 BTrees
 ------
@@ -255,9 +259,9 @@ There is a new transaction package, which provides new interfaces for
 application code and for the interaction between transactions and
 resource managers.
 
-The top-level transaction package has functions commit(), abort(),
-get(), and begin().  They should be used instead of the magic
-get_transaction() builtin, which will be deprecated.  For example:
+The top-level transaction package has functions ``commit()``, ``abort()``,
+``get()``, and ``begin()``.  They should be used instead of the magic
+``get_transaction()`` builtin, which will be deprecated.  For example:
 
     >>> get_transaction().commit()
 
@@ -266,38 +270,38 @@ should now be written as
     >>> import transaction
     >>> transaction.commit()
 
-The new API provides explicit transaction manager objects.  The
-transaction manager (TM) is responsible for associating resource
-managers with a "current" transaction.  It is available as
-`transaction.manager`.  The default TM, implemented by
-ThreadedTransactionManager, assigns each thread its own current
-transaction.  The TransactionManager class assigns all threads to the
-same transaction.
+The new API provides explicit transaction manager objects.  A transaction
+manager (TM) is responsible for associating resource managers with a
+"current" transaction.  The default TM, implemented by class
+``ThreadedTransactionManager``, assigns each thread its own current
+transaction.  This default TM is available as ``transaction.manager``.  The
+``TransactionManager`` class assigns all threads to the same transaction,
+and is an explicit replacement for the ``Connection.setLocalTransaction()``
+method:
 
-A transaction manager instance can be passed as the txn_mgr argument
-to DB.open().  If you do, the connection will use the specified
-transaction manager instead of the default transaction manager.  You
-will need to call commit() and abort() on the transaction manager
-explicitly.  For example:
+A transaction manager instance can be passed as the txn_mgr argument to
+``DB.open()``.  If you do, the connection will use the specified
+transaction manager instead of the default TM.  The current transaction is
+obtained by calling ``get()`` on a TM. For example:
 
     >>> tm = transaction.TransactionManager()
     >>> cn = db.open(txn_mgr=tm)
     [...]
-    >>> tm.commit()
+    >>> tm.get().commit()
 
-The setLocalTransaction() and getTransaction() methods of Connection
-are deprecated.  Use an explicit TM passed via txn_mgr instead.  The
-setLocalTransaction() manager functions still works, but it returns a
-TM instead of a Transaction.
+The ``setLocalTransaction()`` and ``getTransaction()`` methods of
+Connection are deprecated.  Use an explicit TM passed via ``txn_mgr=`` to
+``DB.open()`` instead.  The ``setLocalTransaction()`` method still works,
+but it returns a TM instead of a Transaction.
 
-The TM creates Transaction objects, which are used for exactly one
-transaction.  They have a status() method that returns their current
-state.
+A TM creates Transaction objects, which are used for exactly one
+transaction.  Transaction objects still have ``commit()``, ``abort()``,
+``note()``, ``setUser()``, and ``setExtendedInfo()`` methods.
 
-Resource managers, e.g. Connection or RDB adapter, should use join()
-instead of register().  An object that calls join() manages its own
-resources.  An object that calls register() expects the TM to manage
-the objects.
+Resource managers, e.g. Connection or RDB adapter, should use a
+Transaction's ``join()`` method instead of its ``register()`` method.  An
+object that calls ``join()`` manages its own resources.  An object that
+calls ``register()`` expects the TM to manage the objects.
 
 Data managers written against the ZODB 4 transaction API are now
 supported in ZODB 3.