Fixed #8679: use full signature of Model.save() in docs and remove no-longer-used 'raw' argument

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

docs/ref/contrib/sitemaps.txt

@@ -325,8 +325,8 @@ method::
   
     class Entry(models.Model):
         # ...
-        def save(self):
-            super(Entry, self).save()
+        def save(self, force_insert=False, force_update=False):
+            super(Entry, self).save(force_insert, force_update)
             try:
                 ping_google()
             except Exception:

docs/ref/models/instances.txt

@@ -33,7 +33,7 @@ To save an object back to the database, call ``save()``:
 
 .. method:: Model.save([force_insert=False, force_update=False])
 
-Of course, there's some subtleties; see the sections below.
+Of course, there are some subtleties; see the sections below.
 
 **New in Django development version:** The signature of the ``save()`` method
 has changed from earlier versions (``force_insert`` and ``force_update`` have
@@ -144,38 +144,6 @@ When you save an object, Django performs the following steps:
        is used to provide notification that an object has been successfully
        saved. (These signals are not yet documented.)
 
-Raw saves
-~~~~~~~~~
-
-**New in Django development version**
-
-The pre-processing step (#2 in the previous section) is useful, but it modifies
-the data stored in a field. This can cause problems if you're relying upon the
-data you provide being used as-is.
-
-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.
-
-In cases such as this, you need to prevent pre-processing from being performed
-when you save an object. To do this, you can invoke a **raw save** by passing
-``raw=True`` as an argument to the ``save()`` method::
-
-    b4.save(raw=True) # Save object, but do no pre-processing
-
-A raw save skips the usual data pre-processing that is performed during the
-save. All other steps in the save (pre-save signal, data preparation, data
-insertion, and post-save signal) are performed as normal.
-
-.. admonition:: When to use a raw save
-
-    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
-    conditions.
-
-
 How Django knows to UPDATE vs. INSERT
 -------------------------------------
 

docs/topics/db/models.txt

@@ -683,15 +683,16 @@ You're free to override these methods (and any other model method) to alter
 behavior.
 
 A classic use-case for overriding the built-in methods is if you want something
-to happen whenever you save an object. For example::
+to happen whenever you save an object. For example (see
+:meth:`~Model.save` for documentation of the parameters it accepts)::
 
     class Blog(models.Model):
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
-        def save(self):
+        def save(self, force_insert=False, force_update=False):
             do_something()
-            super(Blog, self).save() # Call the "real" save() method.
+            super(Blog, self).save(force_inset, force_update) # Call the "real" save() method.
             do_something_else()
 
 You can also prevent saving::
@@ -700,11 +701,11 @@ You can also prevent saving::
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
-        def save(self):
+        def save(self, force_insert=False, force_update=False):
             if self.name == "Yoko Ono's blog":
                 return # Yoko shall never have her own blog!
             else:
-                super(Blog, self).save() # Call the "real" save() method.
+                super(Blog, self).save(force_inset, force_update) # Call the "real" save() method.
 
 It's important to remember to call the superclass method -- that's that
 ``super(Blog, self).save()`` business -- to ensure that the object still gets