[1.0.X] Fixed a whole bunch of small docs typos, errors, and ommissions. Backport of the parts of r10371 that apply to the 1.0 docs.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@10372 bcc190cf-cafb-0310-a4f2-bffc1f526a37

3 files changed, 56 insertions, 49 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 96c0440fb3..7a2341f69b 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -129,6 +129,40 @@ what happens with unbound forms::
     >>> f.errors
     {}
 
+Dynamic initial values
+----------------------
+
+.. attribute:: Form.initial
+
+Use ``initial`` to declare the initial value of form fields at runtime. For
+example, you might want to fill in a ``username`` field with the username of the
+current session.
+
+To accomplish this, use the ``initial`` argument to a ``Form``. This argument,
+if given, should be a dictionary mapping field names to initial values. Only
+include the fields for which you're specifying an initial value; it's not
+necessary to include every field in your form. For example::
+
+    >>> f = ContactForm(initial={'subject': 'Hi there!'})
+
+These values are only displayed for unbound forms, and they're not used as
+fallback values if a particular value isn't provided.
+
+Note that if a ``Field`` defines ``initial`` *and* you include ``initial`` when
+instantiating the ``Form``, then the latter ``initial`` will have precedence. In
+this example, ``initial`` is provided both at the field level and at the form
+instance level, and the latter gets precedence::
+
+    >>> class CommentForm(forms.Form):
+    ...     name = forms.CharField(initial='class')
+    ...     url = forms.URLField()
+    ...     comment = forms.CharField()
+    >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)
+    >>> print f
+    <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr>
+    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
+    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
+
 Accessing "clean" data
 ----------------------
 
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index c4c6458a81..dbb87f6012 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -127,6 +127,8 @@ We've specified ``auto_id=False`` to simplify the output::
 The ``initial`` argument lets you specify the initial value to use when
 rendering this ``Field`` in an unbound ``Form``.
 
+To specify dynamic initial data, see the :attr:`Form.initial` parameter.
+
 The use-case for this is when you want to display an "empty" form in which a
 field is initialized to a particular value. For example::
 
@@ -234,7 +236,6 @@ fields. We've specified ``auto_id=False`` to simplify the output::
 
 .. attribute:: Field.error_messages
 
-
 The ``error_messages`` argument lets you override the default messages that the
 field will raise. Pass in a dictionary with keys matching the error messages you
 want to override. For example, here is the default error message::
@@ -256,54 +257,6 @@ And here is a custom error message::
 In the `built-in Field classes`_ section below, each ``Field`` defines the
 error message keys it uses.
 
-Dynamic initial values
-----------------------
-
-The ``initial`` argument to ``Field`` (explained above) lets you hard-code the
-initial value for a ``Field`` -- but what if you want to declare the initial
-value at runtime? For example, you might want to fill in a ``username`` field
-with the username of the current session.
-
-To accomplish this, use the ``initial`` argument to a ``Form``. This argument,
-if given, should be a dictionary mapping field names to initial values. Only
-include the fields for which you're specifying an initial value; it's not
-necessary to include every field in your form. For example::
-
-    >>> class CommentForm(forms.Form):
-    ...     name = forms.CharField()
-    ...     url = forms.URLField()
-    ...     comment = forms.CharField()
-    >>> f = CommentForm(initial={'name': 'your username'}, auto_id=False)
-    >>> print f
-    <tr><th>Name:</th><td><input type="text" name="name" value="your username" /></td></tr>
-    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
-    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
-    >>> f = CommentForm(initial={'name': 'another username'}, auto_id=False)
-    >>> print f
-    <tr><th>Name:</th><td><input type="text" name="name" value="another username" /></td></tr>
-    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
-    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
-
-Just like the ``initial`` parameter to ``Field``, these values are only
-displayed for unbound forms, and they're not used as fallback values if a
-particular value isn't provided.
-
-Finally, note that if a ``Field`` defines ``initial`` *and* you include
-``initial`` when instantiating the ``Form``, then the latter ``initial`` will
-have precedence. In this example, ``initial`` is provided both at the field
-level and at the form instance level, and the latter gets precedence::
-
-    >>> class CommentForm(forms.Form):
-    ...     name = forms.CharField(initial='class')
-    ...     url = forms.URLField()
-    ...     comment = forms.CharField()
-    >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)
-    >>> print f
-    <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr>
-    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
-    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
-
-
 Built-in ``Field`` classes
 --------------------------
 
@@ -785,6 +738,20 @@ example::
         def label_from_instance(self, obj):
             return "My Object #%i" % obj.id
 
+.. attribute:: ModelChoiceField.empty_label
+
+   By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
+   an empty choice at the top of the list. You can change the text of this label
+   (which is ``"---------"`` by default) with the ``empty_label`` attribute, or
+   you can disable the empty label entirely by setting ``empty_label`` to
+   ``None``::
+   
+        # A custom empty label
+        field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
+        
+        # No empty label
+        field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+
 ``ModelMultipleChoiceField``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 364e664fc1..9d7fbae493 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -53,6 +53,8 @@ commonly used groups of widgets:
 .. class:: Select
 
     Select widget: ``<select><option ...>...</select>``
+    
+    Requires that your field provides :attr:`~Field.choices`.
 
 .. class:: NullBooleanSelect
 
@@ -63,6 +65,8 @@ commonly used groups of widgets:
     Select widget allowing multiple selection: ``<select
     multiple='multiple'>...</select>``
 
+    Requires that your field provides :attr:`~Field.choices`.
+
 .. class:: RadioSelect
 
     A list of radio buttons:
@@ -73,6 +77,8 @@ commonly used groups of widgets:
           <li><input type='radio' ...></li>
           ...
         </ul>
+        
+    Requires that your field provides :attr:`~Field.choices`.
 
 .. class:: CheckboxSelectMultiple