Edited docs/db-api.txt changes from [5700]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5709 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/db-api.txt

@@ -125,27 +125,31 @@ When you save an object, Django performs the following steps:
 
     1. **Emit a ``pre_save`` signal.** This provides a notification that
        an object is about to be saved. You can register a listener that
-       will be invoked whenever this signal is emitted.
+       will be invoked whenever this signal is emitted. (These signals are
+       not yet documented.)
 
     2. **Pre-process the data.** Each field on the object is asked to
        perform any automated data modification that the field may need
        to perform.
 
-       Most fields do *no* pre-processing - the field data is kept as-is.
+       Most fields do *no* pre-processing -- the field data is kept as-is.
        Pre-processing is only used on fields that have special behavior.
        For example, if your model has a ``DateField`` with ``auto_now=True``,
        the pre-save phase will alter the data in the object to ensure that
-       the date field contains the current date stamp.
+       the date field contains the current date stamp. (Our documentation
+       doesn't yet include a list of all the fields with this "special
+       behavior.")
 
     3. **Prepare the data for the database.** Each field is asked to provide
-       their current value in a datatype that can be written to the database.
+       its current value in a data type that can be written to the database.
 
-       Again, most fields require *no* data preparation. Simple data types,
+       Most fields require *no* data preparation. Simple data types, such as
-       such as integers and strings, are 'ready to write' as a Python object.
+       integers and strings, are 'ready to write' as a Python object. However,
-       However, more complex data types often require some modification. For
+       more complex data types often require some modification.
-       example, ``DateFields`` use a Python ``datetime`` object to store data.
+
-       Databases don't store ``datetime`` objects, so the field value
+       For example, ``DateFields`` use a Python ``datetime`` object to store
-       must be converted into an ISO compliant date string for insertion
+       data. Databases don't store ``datetime`` objects, so the field value
+       must be converted into an ISO-compliant date string for insertion
        into the database.
 
     4. **Insert the data into the database.** The pre-processed, prepared
@@ -154,18 +158,18 @@ When you save an object, Django performs the following steps:
 
     5. **Emit a ``post_save`` signal.** As with the ``pre_save`` signal, this
        is used to provide notification that an object has been successfully
-       saved.
+       saved. (These signals are not yet documented.)
 
 Raw Saves
 ~~~~~~~~~
 
 **New in Django development version**
 
-The pre-processing step performed by Django is extremely useful for
+The pre-processing step (#2 in the previous section) is useful, but it modifies
-implementing special field behavior (such as the ``auto_now`` feature of
+the data stored in a field. This can cause problems if you're relying upon the
-``DateField``), but it does modify the data stored in a field. This can cause
+data you provide being used as-is.
-problems if you are relying upon the data you provide being used as-is. For
+
-example, if you are setting up conditions for a test, you will want the test
+For example, if you're setting up conditions for a test, you'll want the test
 conditions to be repeatable. If pre-processing is performed, the data used
 to specify test conditions may be modified, changing the conditions for the
 test each time the test is run.
@@ -182,10 +186,10 @@ insertion, and post-save signal) are performed as normal.
 
 .. admonition:: When to use a raw save
 
-    Generally speaking, you shouldn't need use use a raw save. Disabling field
+    Generally speaking, you shouldn't need to use a raw save. Disabling field
     pre-processing is an extraordinary measure that should only be required
-    in extraordinary circumstances (such as setting up reliable test
+    in extraordinary circumstances, such as setting up reliable test
-    conditions).
+    conditions.
 
 Saving changes to objects
 =========================