Ticket #4737: diff.txt

Index: docs/model-api.txt
===================================================================
--- docs/model-api.txt  (revision 5490)
+++ docs/model-api.txt  (working copy)
@@ -471,8 +471,15 @@
 Field options
 -------------
 
-The following arguments are available to all field types. All are optional.
+All field types can take a number of options. These are split into two main
+categories: those affecting how the field is represented in the database, and
+those affecting the field's display and validation.
 
+Field option affecting validation are only used by components which recognise 
+them, i.e. the admin interface and the form component.
+
+### Database Options
+
 ``null``
 ~~~~~~~~
 
@@ -492,6 +499,48 @@
 possible values for "no data;" Django convention is to use the empty
 string, not ``NULL``.
 
+``db_column``
+~~~~~~~~~~~~~
+
+The name of the database column to use for this field. If this isn't given,
+Django will use the field's name.
+
+If your database column name is an SQL reserved word, or contains
+characters that aren't allowed in Python variable names -- notably, the
+hyphen -- that's OK. Django quotes column and table names behind the
+scenes.
+
+``db_index``
+~~~~~~~~~~~~
+
+If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
+statement for this field.
+
+``primary_key``
+~~~~~~~~~~~~~~~
+
+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 this field::
+
+    id = models.AutoField('ID', primary_key=True)
+
+Thus, you don't need to set ``primary_key=True`` on any of your fields
+unless you want to override the default primary-key behavior.
+
+``primary_key=True`` implies ``blank=False``, ``null=False`` and
+``unique=True``. Only one primary key is allowed on an object.
+
+``unique``
+~~~~~~~~~~
+
+If ``True``, this field must be unique throughout the table.
+
+This is enforced at the database level and at the Django admin-form level.
+
+### Display and Validation
+
 ``blank``
 ~~~~~~~~~
 
@@ -569,23 +618,6 @@
 Django admin site. Essentially, this means you should put ``core=True`` on all
 required fields in your related object that is being edited inline.
 
-``db_column``
-~~~~~~~~~~~~~
-
-The name of the database column to use for this field. If this isn't given,
-Django will use the field's name.
-
-If your database column name is an SQL reserved word, or contains
-characters that aren't allowed in Python variable names -- notably, the
-hyphen -- that's OK. Django quotes column and table names behind the
-scenes.
-
-``db_index``
-~~~~~~~~~~~~
-
-If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
-statement for this field.
-
 ``default``
 ~~~~~~~~~~~
 
@@ -605,22 +637,6 @@
 form. It's useful for documentation even if your object doesn't have an
 admin form.
 
-``primary_key``
-~~~~~~~~~~~~~~~
-
-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 this field::
-
-    id = models.AutoField('ID', primary_key=True)
-
-Thus, you don't need to set ``primary_key=True`` on any of your fields
-unless you want to override the default primary-key behavior.
-
-``primary_key=True`` implies ``blank=False``, ``null=False`` and
-``unique=True``. Only one primary key is allowed on an object.
-
 ``radio_admin``
 ~~~~~~~~~~~~~~~
 
@@ -631,13 +647,6 @@
 Don't use this for a field unless it's a ``ForeignKey`` or has ``choices``
 set.
 
-``unique``
-~~~~~~~~~~
-
-If ``True``, this field must be unique throughout the table.
-
-This is enforced at the database level and at the Django admin-form level.
-
 ``unique_for_date``
 ~~~~~~~~~~~~~~~~~~~