Tidy up some of the transaction documentation.

.. function:: atomic(using=None, savepoint=True)

    This function creates an atomic block for writes to the database.

    (Atomicity is the defining property of database transactions.)

    Atomicity is the defining property of database transactions. ``atomic``

    allows us to create a block of code within which the atomicity on the

    database is guaranteed. If the block of code is successfully completed, the

    changes are committed to the database. If there is an exception, the

    changes are rolled back.

    When the block completes successfully, the changes are committed to the

    database. When it raises an exception, the changes are rolled back.

    ``atomic`` can be nested. In this case, when an inner block completes

    successfully, its effects can still be rolled back if an exception is

    raised in the outer block at a later point.

    ``atomic`` takes a ``using`` argument which should be the name of a

    database. If this argument isn't provided, Django uses the ``"default"``

    database.

    ``atomic`` blocks can be nested. In this case, when an inner block

    completes successfully, its effects can still be rolled back if an

    exception is raised in the outer block at a later point.

    ``atomic`` is usable both as a `decorator`_::

        @transaction.atomic

        def viewfunc(request):

            do_stuff()

            create_parent()

            try:

                with transaction.atomic():

                    do_stuff_that_could_fail()

                    generate_relationships()

            except IntegrityError:

                handle_exception()

            do_more_stuff()

            add_children()

    In this example, even if ``do_stuff_that_could_fail()`` causes a database

    In this example, even if ``generate_relationships()`` causes a database

    error by breaking an integrity constraint, you can execute queries in

    ``do_more_stuff()``, and the changes from ``do_stuff()`` are still there.

    ``add_children()``, and the changes from ``create_parent()`` are still

    there. Note that any operations attempted in ``generate_relationships()``

    will already have been rolled back safely when ``handle_exception()`` is

    called, so the exception handler can also operate on the database if

    necessary.

    In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting

    to commit, roll back, or change the autocommit state of the database

    connection within an ``atomic`` block will raise an exception.

    ``atomic`` takes a ``using`` argument which should be the name of a

    database. If this argument isn't provided, Django uses the ``"default"``

    database.

    Under the hood, Django's transaction management code:

    - opens a transaction when entering the outermost ``atomic`` block;

The three functions described above relied on a concept called "transaction

states". This mechanisme was deprecated in Django 1.6, but it's still

available until Django 1.8..

available until Django 1.8.

At any time, each database connection is in one of these two states: