A whole lotta documentation fixes: Fixes #8704, #8826, #8980, #9243, #9343, #9529,

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

11 files changed, 78 insertions, 31 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 7f71aca450..4592eab862 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -832,8 +832,17 @@ It is important you use a ``ModelForm`` here otherwise things can break. See the
 ============================
 
 The admin interface has the ability to edit models on the same page as a
-parent model. These are called inlines. You can add them to a model by
-specifying them in a ``ModelAdmin.inlines`` attribute::
+parent model. These are called inlines. Suppose you have these two models::
+
+     class Author(models.Model):
+        name = models.CharField(max_length=100)
+
+     class Book(models.Model):
+        author = models.ForeignKey(Author)
+        title = models.CharField(max_length=100)
+
+You can edit the books authored by an author on the author page. You add 
+inlines to a model by specifying them in a ``ModelAdmin.inlines``::
 
     class BookInline(admin.TabularInline):
         model = Book
@@ -1165,7 +1174,7 @@ Hooking ``AdminSite`` instances into your URLconf
 
 The last step in setting up the Django admin is to hook your ``AdminSite``
 instance into your URLconf. Do this by pointing a given URL at the
-``AdminSite.root`` method.
+``AdminSite.urls`` method.
 
 In this example, we register the default ``AdminSite`` instance
 ``django.contrib.admin.site`` at the URL ``/admin/`` ::
diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
index 10a7dcf00f..36151d5fbf 100644
--- a/docs/ref/contrib/comments/index.txt
+++ b/docs/ref/contrib/comments/index.txt
@@ -155,9 +155,10 @@ A complete form might look like::
     {% get_comment_form for event as form %}
     <form action="{% comment_form_target %}" method="POST">
       {{ form }}
-      <p class="submit">
-        <input type="submit" name="preview" class="submit-post" value="Preview">
-      </p>
+      <tr>
+        <td></td>
+        <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
+      </tr>
     </form>
     
 Be sure to read the `notes on the comment form`_, below, for some special
diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt
index 42a8a8142b..23188c67e7 100644
--- a/docs/ref/contrib/contenttypes.txt
+++ b/docs/ref/contrib/contenttypes.txt
@@ -324,6 +324,14 @@ same types of lookups manually::
     ...                           object_id=b.id)
     [<TaggedItem: django>, <TaggedItem: python>]
 
+Note that if the model with a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` 
+that you're referring to uses a non-default value for ``ct_field`` or ``fk_field`` 
+(e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), 
+you'll need to pass ``content_type_field`` and ``object_id_field`` to
+:class:`~django.contrib.contenttypes.generic.GenericRelation`.::
+
+	comments = generic.GenericRelation(Comment, content_type_field="content_type", object_id_field="object_pk")
+	
 Note that if you delete an object that has a
 :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects
 which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt
index cf57e79884..c81c24242a 100644
--- a/docs/ref/contrib/formtools/form-wizard.txt
+++ b/docs/ref/contrib/formtools/form-wizard.txt
@@ -290,7 +290,7 @@ Advanced FormWizard methods
 .. method:: FormWizard.render_template
 
     Renders the template for the given step, returning an
-    :class:`~django.http.HttpResponseRedirect` object.
+    :class:`~django.http.HttpResponse` object.
 
     Override this method if you want to add a custom context, return a different
     MIME type, etc. If you only need to override the template name, use
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 33601ef9d0..57f2045bad 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -87,8 +87,8 @@ MySQL notes
 ===========
 
 Django expects the database to support transactions, referential integrity,
-and Unicode (UTF-8 encoding). Fortunately, MySQL_ has all these
-features available as far back as 3.23. While it may be possible to use
+and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these
+features as available as far back as 3.23. While it may be possible to use
 3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0.
 
 MySQL 4.1
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 7c34344c2c..60ed244d17 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -341,6 +341,9 @@ would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
 application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
 
+When fixture files are processed, the data is saved to the database as is.
+Model defined ``save`` methods and ``pre_save`` signals are not called.
+
 Note that the order in which fixture files are processed is undefined. However,
 all fixture data is installed as a single transaction, so data in
 one fixture can reference data in another fixture. If the database backend
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 4248af3d26..d1ff54908d 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -174,6 +174,16 @@ validation if a particular field's value is not given. ``initial`` values are
     >>> f.errors
     {'url': [u'This field is required.'], 'name': [u'This field is required.']}
 
+Instead of a constant, you can also pass any callable::
+
+    >>> import datetime
+    >>> class DateForm(forms.Form):
+    ...     day = forms.DateField(initial=datetime.date.today)
+    >>> print DateForm()
+    <tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" /><td></tr>
+
+The callable will be evaluated only when the unbound form is displayed, not when it is defined.
+
 ``widget``
 ~~~~~~~~~~
 
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 62127884b6..42a44bf920 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -7,6 +7,8 @@ Model field reference
 .. module:: django.db.models.fields
    :synopsis: Built-in field types.
 
+.. currentmodule:: django.db.models
+
 This document contains all the gory details about all the `field options`_ and
 `field types`_ Django's got to offer.
 
@@ -45,11 +47,11 @@ booleans and dates. For both types of fields, you will also need to set
 :attr:`~Field.blank`).
 
 Avoid using :attr:`~Field.null` on string-based fields such as
-:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`
-unless you have an excellent reason. If a string-based field has ``null=True``,
-that means it has two possible values for "no data": ``NULL``, and the empty
-string. In most cases, it's redundant to have two possible values for "no
-data;" Django convention is to use the empty string, not ``NULL``.
+:class:`CharField` and :class:`TextField` unless you have an excellent reason.
+If a string-based field has ``null=True``, that means it has two possible values
+for "no data": ``NULL``, and the empty string. In most cases, it's redundant to
+have two possible values for "no data;" Django convention is to use the empty
+string, not ``NULL``.
 
 .. note::
 
@@ -142,9 +144,8 @@ documentation.
 Finally, note that choices can be any iterable object -- not necessarily a list
 or tuple. This lets you construct choices dynamically. But if you find yourself
 hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a
-proper database table with a :class:`~django.db.models.ForeignKey`.
-:attr:`~Field.choices` is meant for static data that doesn't change much, if
-ever.
+proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is
+meant for static data that doesn't change much, if ever.
 
 ``db_column``
 -------------
@@ -220,10 +221,10 @@ Alternatively you can use plain text and
 If ``True``, this field is the primary key for the model.
 
 If you don't specify ``primary_key=True`` for any fields in your model, Django
-will automatically add an :class:`~django.db.models.IntegerField` to hold the
-primary key, so you don't need to set ``primary_key=True`` on any of your
-fields unless you want to override the default primary-key behavior. For more,
-see :ref:`automatic-primary-key-fields`.
+will automatically add an :class:`IntegerField` to hold the primary key, so you
+don't need to set ``primary_key=True`` on any of your fields unless you want to
+override the default primary-key behavior. For more, see
+:ref:`automatic-primary-key-fields`.
 
 ``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
 Only one primary key is allowed on an object.
@@ -240,18 +241,16 @@ you try to save a model with a duplicate value in a :attr:`~Field.unique`
 field, a :exc:`django.db.IntegrityError` will be raised by the model's
 :meth:`~django.db.models.Model.save` method.
 
-This option is valid on all field types except
-:class:`~django.db.models.ManyToManyField` and
-:class:`~django.db.models.FileField`.
+This option is valid on all field types except :class:`ManyToManyField` and
+:class:`FileField`.
 
 ``unique_for_date``
 -------------------
 
 .. attribute:: Field.unique_for_date
 
-Set this to the name of a :class:`~django.db.models.DateField` or
-:class:`~django.db.models.DateTimeField` to require that this field be unique
-for the value of the date field.
+Set this to the name of a :class:`DateField` or :class:`DateTimeField` to
+require that this field be unique for the value of the date field.
 
 For example, if you have a field ``title`` that has
 ``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two
@@ -734,7 +733,10 @@ A :class:`CharField` for a URL. Has one extra optional argument:
 .. attribute:: URLField.verify_exists
 
     If ``True`` (the default), the URL given will be checked for existence
-    (i.e., the URL actually loads and doesn't give a 404 response).
+    (i.e., the URL actually loads and doesn't give a 404 response). It should
+    be noted that when using the single-threaded development server, validating
+    a url being serverd by the same server will hang.
+    This should not be a problem for multithreaded servers.
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 847cebf1e9..4124e78513 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -154,7 +154,7 @@ In SQL terms, that evaluates to::
 
     SELECT ...
     WHERE NOT pub_date > '2005-1-3'
-    AND NOT headline = 'Hello'
+    OR NOT headline = 'Hello'
 
 Note the second example is more restrictive.
 
@@ -1484,8 +1484,18 @@ search
 A boolean full-text search, taking advantage of full-text indexing. This is
 like ``contains`` but is significantly faster due to full-text indexing.
 
+Example::
+    
+    Entry.objects.filter(headline__search="+Django -jazz Python")
+
+SQL equivalent::
+
+    SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE);
+
 Note this is only available in MySQL and requires direct manipulation of the
-database to add the full-text index.
+database to add the full-text index. By default Django uses BOOLEAN MODE for
+full text searches. `Please check MySQL documentation for additional details. <http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
+
 
 regex
 ~~~~~
diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt
index d0906942e8..9aec52c2b5 100644
--- a/docs/ref/models/relations.txt
+++ b/docs/ref/models/relations.txt
@@ -42,7 +42,7 @@ Extra methods on managers when used in a ForeignKey context
         ....     body_text='Hi', 
         ....     pub_date=datetime.date(2005, 1, 1)
         .... )
-        >>> e.save()
+        >>> e.save(force_insert=True)
 
     Note that there's no need to specify the keyword argument of the model that
     defines the relationship. In the above example, we don't pass the parameter
diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
index b83b12c66c..87e1ce3b77 100644
--- a/docs/ref/signals.txt
+++ b/docs/ref/signals.txt
@@ -30,6 +30,10 @@ module system.
     If you override these methods on your model, you must call the parent class'
     methods for this signals to be sent.
 
+	Note also that Django stores signal handlers as weak references by default,
+	so if your handler is a local function, it may be garbage collected.  To
+	prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
+
 pre_init
 --------