magic-removal: Did some proofreading to docs/model-api.txt. Not yet done.

git-svn-id: http://code.djangoproject.com/svn/django/branches/magic-removal@2799 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/model-api.txt

@@ -10,66 +10,408 @@ The basics:
 
     * Each model is a Python class that subclasses ``django.db.models.Model``.
     * Each attribute of the model represents a database field.
-    * Model metadata (non-field information) goes in an inner class named ``Meta``.
+    * Model metadata (non-field information) goes in an inner class named
-    * Metadata used for administration purposes goes into an inner class named ``Admin``.
+      ``Meta``.
+    * Metadata used for Django's admin site goes into an inner class named
+      ``Admin``.
+    * With all of this, Django gives you an automatically-generated
+      database-access API, which is explained in the `Database API reference`_.
 
 A companion to this document is the `official repository of model examples`_.
 
-.. _`official repository of model examples`: http://www.djangoproject.com/documentation/models/
+.. _Database API reference: http://www.djangoproject.com/documentation/db_api/
+.. _official repository of model examples: http://www.djangoproject.com/documentation/models/
 
-Field objects
+Quick example
 =============
 
-The most important part of a model is the list of database fields it defines.
+This example model defines a ``Person``, which has a ``first_name`` and
-Fields are defined by class attributes.
+``last_name``::
 
-In this example, there are two fields, ``first_name`` and ``last_name`` ::
+    from django.db import models
 
     class Person(models.Model):
         first_name = models.CharField(maxlength=30)
         last_name = models.CharField(maxlength=30)
 
-Django will use ``first_name`` and ``last_name`` as the database column names.
+``first_name`` and ``last_name`` are *fields* of the model. Each field is
+specified as a class attribute, and each attribute maps to a database column.
 
-Each field type, except for ``ForeignKey``, ``ManyToManyField`` and
+The above ``Person`` model would create an SQL table like this::
-``OneToOneField``, takes an optional first positional argument -- a
-human-readable name. If the human-readable name isn't given, Django will
-automatically create the human-readable name by using the machine-readable
-name, converting underscores to spaces.
 
-In this example, the human-readable name is ``"Person's first name"``::
+    CREATE TABLE myapp_person (
+        "id" serial NOT NULL PRIMARY KEY,
+        "first_name" varchar(30) NOT NULL,
+        "last_name" varchar(30) NOT NULL
+    );
 
-    first_name = models.CharField("Person's first name", maxlength=30)
+Three technical notes:
 
-In this example, the human-readable name is ``"first name"``::
+    * The name of the table, ``myapp_person``, is automatically derived from
+      some model metadata but can be overridden. See _`Table names` below.
+    * An ``id`` field is added automatically, but this behavior can be
+      overriden. See _`Automatic primary key fields` below.
+    * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
+      syntax, but it's worth noting Django uses SQL tailored to the database
+      backend specified in your `settings file`_.
 
-    first_name = models.CharField(maxlength=30)
+.. _settings file: http://www.djangoproject.com/documentation/settings/
 
-``ForeignKey``, ``ManyToManyField`` and ``OneToOneField`` require the first
+Fields
-argument to be a model class, so use the ``verbose_name`` keyword argument to
+======
-specify the human-readable name::
 
-    poll = models.ForeignKey(Poll, verbose_name="the related poll")
+The most important part of a model -- and the only required part of a model --
-    sites = models.ManyToManyField(Site, verbose_name="list of sites")
+is the list of database fields it defines. Fields are specified by class
-    place = models.OneToOneField(Place, verbose_name="related place")
+attributes.
 
-Convention is not to capitalize the first letter of the ``verbose_name``.
+Example::
-Django will automatically capitalize the first letter where it needs to.
+
+    class Musician(models.Model):
+        first_name = models.CharField(maxlength=50)
+        last_name = models.CharField(maxlength=50)
+        instrument = models.CharField(maxlength=100)
+
+    class Album(models.Model):
+        artist = models.ForeignKey(Musician)
+        name = models.CharField(maxlength=100)
+        release_date = models.DateField()
+        num_stars = models.IntegerField()
 
 Field name restrictions
 -----------------------
 
-TODO: Fill this section.
+Django places only two restrictions on model field names:
 
-    * Can't be Python reserved word.
+    1. A field name cannot be a Python reserved word, because that would result
-    * Can't have more than one underscore in a row, due to query lookup.
+       in a Python syntax error. For example::
 
-General field options
+           class Example(models.Model):
----------------------
+               pass = models.IntegerField() # 'pass' is a reserved word!
+
+    2. A field name cannot contain more than one underscore in a row, due to
+       the way Django's query lookup syntax works. For example::
+
+           class Example(models.Model):
+               foo__bar = models.IntegerField() 'foo__bar' has two underscores!
+
+These limitations can be worked around, though, because your field name doesn't
+necessarily have to match your database column name. See `db_column`_ below.
+
+SQL reserved words, such as ``join``, ``where`` or ``select`, *are* allowed as
+model field names, because Django escapes all database table names and column
+names in every underlying SQL query. It uses the quoting syntax of your
+particular database engine.
+
+Field types
+-----------
+
+Each field in your model should be an instance of the appropriate ``Field``
+class. Django uses the field class types to determine a few things:
+
+    * The database column type (e.g. ``INTEGER``, ``VARCHAR``).
+    * The widget to use in Django's admin interface, if you care to use it
+      (e.g. ``<input type="text">``, ``<select>``).
+    * The minimal validation requirements, used in Django's admin and in
+      manipulators.
+
+Here are all available field types:
+
+``AutoField``
+~~~~~~~~~~~~~
+
+An ``IntegerField`` that automatically increments according to available IDs.
+You usually won't need to use this directly; a primary key field will
+automatically be added to your model if you don't specify otherwise. See
+_`Automatic primary key fields`.
+
+``BooleanField``
+~~~~~~~~~~~~~~~~
+
+A true/false field.
+
+The admin represents this as a checkbox.
+
+``CharField``
+~~~~~~~~~~~~~
+
+A string field, for small- to large-sized strings.
+
+For large amounts of text, use ``TextField``.
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``CharField`` has an extra required argument, ``maxlength``, the maximum length
+(in characters) of the field. The maxlength is enforced at the database level
+and in Django's validation.
+
+``CommaSeparatedIntegerField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A field of integers separated by commas. As in ``CharField``, the ``maxlength``
+argument is required.
+
+``DateField``
+~~~~~~~~~~~~~
+
+A date field. Has a few extra optional arguments:
+
+    ======================  ===================================================
+    Argument                Description
+    ======================  ===================================================
+    ``auto_now``            Automatically set the field to now every time the
+                            object is saved. Useful for "last-modified"
+                            timestamps.
+
+    ``auto_now_add``        Automatically set the field to now when the object
+                            is first created. Useful for creation of
+                            timestamps.
+    ======================  ===================================================
+
+The admin represents this as an ``<input type="text">`` with a JavaScript
+calendar and a shortcut for "Today."
+
+``DateTimeField``
+~~~~~~~~~~~~~~~~~
+
+A date and time field. Takes the same extra options as ``DateField``.
+
+The admin represents this as two ``<input type="text">`` fields, with
+JavaScript shortcuts.
+
+``EmailField``
+~~~~~~~~~~~~~~
+
+A ``CharField`` that checks that the value is a valid e-mail address.
+This doesn't accept ``maxlength``.
+
+``FileField``
+~~~~~~~~~~~~~
+
+A file-upload field.
+
+Has an extra required argument, ``upload_to``, a local filesystem path to
+which files should be upload. This path may contain `strftime formatting`_,
+which will be replaced by the date/time of the file upload (so that
+uploaded files don't fill up the given directory).
+
+The admin represents this as an ``<input type="file">`` (a file-upload widget).
+
+Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few
+steps:
+
+    1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the
+        full path to a directory where you'd like Django to store uploaded
+        files. (For performance, these files are not stored in the database.)
+        Define ``MEDIA_URL`` as the base public URL of that directory. Make
+        sure that this directory is writable by the Web server's user
+        account.
+
+    2. Add the ``FileField`` or ``ImageField`` to your model, making sure
+        to define the ``upload_to`` option to tell Django to which
+        subdirectory of ``MEDIA_ROOT`` it should upload files.
+
+    3. All that will be stored in your database is a path to the file
+        (relative to ``MEDIA_ROOT``). You'll must likely want to use the
+        convenience ``get_<fieldname>_url`` function provided by Django. For
+        example, if your ``ImageField`` is called ``mug_shot``, you can get
+        the absolute URL to your image in a template with ``{{
+        object.get_mug_shot_url }}``.
+
+.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
+
+``FilePathField``
+~~~~~~~~~~~~~~~~~
+
+A field whose choices are limited to the filenames in a certain directory
+on the filesystem. Has three special arguments, of which the first is
+required:
+
+    ======================  ===================================================
+    Argument                Description
+    ======================  ===================================================
+    ``path``                Required. The absolute filesystem path to a
+                            directory from which this ``FilePathField`` should
+                            get its choices. Example: ``"/home/images"``.
+
+    ``match``               Optional. A regular expression, as a string, that
+                            ``FilePathField`` will use to filter filenames.
+                            Note that the regex will be applied to the
+                            base filename, not the full path. Example:
+                            ``"foo.*\.txt^"``, which will match a file called
+                            ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.
+
+    ``recursive``           Optional. Either ``True`` or ``False``. Default is
+                            ``False``. Specifies whether all subdirectories of
+                            ``path`` should be included.
+    ======================  ===================================================
+
+Of course, these arguments can be used together.
+
+The one potential gotcha is that ``match`` applies to the base filename,
+not the full path. So, this example::
+
+    FilePathField(path="/home/images", match="foo.*", recursive=True)
+
+...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``
+because the ``match`` applies to the base filename (``foo.gif`` and
+``bar.gif``).
+
+``FloatField``
+~~~~~~~~~~~~~~
+
+A floating-point number. Has two **required** arguments:
+
+    ======================  ===================================================
+    Argument                Description
+    ======================  ===================================================
+    ``max_digits``          The maximum number of digits allowed in the number.
+
+    ``decimal_places``      The number of decimal places to store with the
+                            number.
+    ======================  ===================================================
+
+For example, to store numbers up to 999 with a resolution of 2 decimal places,
+you'd use::
+
+    models.FloatField(..., max_digits=5, decimal_places=2)
+
+And to store numbers up to approximately one billion with a resolution of 10
+decimal places::
+
+    models.FloatField(..., max_digits=19, decimal_places=10)
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``ImageField``
+~~~~~~~~~~~~~~
+
+Like ``FileField``, but validates that the uploaded object is a valid
+image. Has two extra optional arguments, ``height_field`` and
+``width_field``, which, if set, will be auto-populated with the height and
+width of the image each time a model instance is saved.
+
+Requires the `Python Imaging Library`_.
+
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
+``IntegerField``
+~~~~~~~~~~~~~~~~
+
+An integer.
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``IPAddressField``
+~~~~~~~~~~~~~~~~~~
+
+An IP address, in string format (i.e. "24.124.1.30").
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``NullBooleanField``
+~~~~~~~~~~~~~~~~~~~~
+
+Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this
+instead of a ``BooleanField`` with ``null=True``.
+
+The admin represents this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
+
+``PhoneNumberField``
+~~~~~~~~~~~~~~~~~~~~
+
+A ``CharField`` that checks that the value is a valid U.S.A.-style phone
+number (in the format ``XXX-XXX-XXXX``).
+
+``PositiveIntegerField``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Like an ``IntegerField``, but must be positive.
+
+``PositiveSmallIntegerField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Like a ``PositiveIntegerField``, but only allows values under a certain
+(database-dependent) point.
+
+``SlugField``
+~~~~~~~~~~~~~
+
+"Slug" is a newspaper term. A slug is a short label for something,
+containing only letters, numbers, underscores or hyphens. They're generally
+used in URLs.
+
+In the Django development version, you can specify ``maxlength``. If
+``maxlength`` is not specified, Django will use a default length of 50. In
+previous Django versions, there's no way to override the length of 50.
+
+Implies ``db_index=True``.
+
+Accepts an extra option, ``prepopulate_from``, which is a list of fields
+from which to auto-populate the slug, via JavaScript, in the object's admin
+form::
+
+    models.SlugField(prepopulate_from=("pre_name", "name"))
+
+``prepopulate_from`` doesn't accept DateTimeFields.
+
+The admin represents ``SlugField`` as an ``<input type="text">`` (a
+single-line input).
+
+``SmallIntegerField``
+~~~~~~~~~~~~~~~~~~~~~
+
+Like an ``IntegerField``, but only allows values under a certain
+(database-dependent) point.
+
+``TextField``
+~~~~~~~~~~~~~
+
+A large text field.
+
+The admin represents this as a ``<textarea>`` (a multi-line input).
+
+``TimeField``
+~~~~~~~~~~~~~
+
+A time. Accepts the same auto-population options as ``DateField`` and
+``DateTimeField``.
+
+The admin represents this as an ``<input type="text">`` with some
+JavaScript shortcuts.
+
+``URLField``
+~~~~~~~~~~~~
+
+A field for a URL. If the ``verify_exists`` option is ``True`` (default),
+the URL given will be checked for existence (i.e., the URL actually loads
+and doesn't give a 404 response).
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``USStateField``
+~~~~~~~~~~~~~~~~
+
+A two-letter U.S. state abbreviation.
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``XMLField``
+~~~~~~~~~~~~
+
+A ``TextField`` that checks that the value is valid XML that matches a
+given schema. Takes one required argument, ``schema_path``, which is the
+filesystem path to a RelaxNG_ schema against which to validate the field.
+
+.. _RelaxNG: http://www.relaxng.org/
+
+Field options
+-------------
 
 The following arguments are available to all field types. All are optional.
 
 ``null``
+~~~~~~~~
+
 If ``True``, Django will store empty values as ``NULL`` in the database.
 Default is ``False``.
 
@@ -85,6 +427,8 @@ The following arguments are available to all field types. All are optional.
 string, not ``NULL``.
 
 ``blank``
+~~~~~~~~~
+
 If ``True``, the field is allowed to be blank.
 
 Note that this is different than ``null``. ``null`` is purely
@@ -93,6 +437,8 @@ The following arguments are available to all field types. All are optional.
 empty value. If a field has ``blank=False``, the field will be required.
 
 ``choices``
+~~~~~~~~~~~
+
 A list of 2-tuples to use as choices for this field.
 
 If this is given, Django's admin will use a select box instead of the
@@ -130,6 +476,8 @@ The following arguments are available to all field types. All are optional.
         gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
 
 ``core``
+~~~~~~~~
+
 For objects that are edited inline to a related object.
 
 In the Django admin, if all "core" fields in an inline-edited object are
@@ -139,6 +487,8 @@ The following arguments are available to all field types. All are optional.
 ``core=True`` field.
 
 ``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.
 
@@ -148,21 +498,31 @@ The following arguments are available to all field types. All are optional.
 scenes.
 
 ``db_index``
+~~~~~~~~~~~~
+
 If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
 statement for this field.
 
 ``default``
+~~~~~~~~~~~
+
 The default value for the field.
 
 ``editable``
+~~~~~~~~~~~~
+
 If ``False``, the field will not be editable in the admin. Default is  ``True``.
 
 ``help_text``
+~~~~~~~~~~~~~
+
 Extra "help" text to be displayed under the field on the object's admin
 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,
@@ -177,6 +537,8 @@ The following arguments are available to all field types. All are optional.
 ``unique=True``. Only one primary key is allowed on an object.
 
 ``radio_admin``
+~~~~~~~~~~~~~~~
+
 By default, Django's admin uses a select-box interface (<select>) for
 fields that are ``ForeignKey`` or have ``choices`` set. If ``radio_admin``
 is set to ``True``, Django will use a radio-button interface instead.
@@ -185,11 +547,15 @@ The following arguments are available to all field types. All are optional.
 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``
+~~~~~~~~~~~~~~~~~~~
+
 Set this to the name of a ``DateField`` or ``DateTimeField`` to require
 that this field be unique for the value of the date field.
 
@@ -200,13 +566,19 @@ The following arguments are available to all field types. All are optional.
 This is enforced at the Django admin-form level but not at the database level.
 
 ``unique_for_month``
+~~~~~~~~~~~~~~~~~~~~
+
 Like ``unique_for_date``, but requires the field to be unique with respect
 to the month.
 
 ``unique_for_year``
+~~~~~~~~~~~~~~~~~~~
+
 Like ``unique_for_date`` and ``unique_for_month``.
 
 ``validator_list``
+~~~~~~~~~~~~~~~~~~
+
 A list of extra validators to apply to the field. Each should be a callable
 that takes the parameters ``field_data, all_data`` and raises
 ``django.core.validators.ValidationError`` for errors. (See the
@@ -216,257 +588,31 @@ The following arguments are available to all field types. All are optional.
 
 .. _validator docs: http://www.djangoproject.com/documentation/forms/#validators
 
-Field types
+Verbose field names
------------
+-------------------
 
-Each field in your model should be an instance of the appropriate ``Field``
+Each field type, except for ``ForeignKey``, ``ManyToManyField`` and
-class. Django uses the field class types to determine a few things:
+``OneToOneField``, takes an optional first positional argument -- a
+verbose name. If the verbose name isn't given, Django will automatically create
+it using the field's attribute name, converting underscores to spaces.
 
-    * The database column type (e.g. ``INTEGER``, ``VARCHAR``).
+In this example, the verbose name is ``"Person's first name"``::
-    * The widget to use in Django's admin (e.g. ``<input type="text">``, ``<select>``).
-    * The minimal validation requirements, used in Django's admin and in manipulators.
 
-Here are all available field types:
+    first_name = models.CharField("Person's first name", maxlength=30)
 
-``AutoField``
+In this example, the verbose name is ``"first name"``::
-    An ``IntegerField`` that automatically increments according to available
-    IDs. You usually won't need to use this directly; a primary key field will
-    automatically be added to your model if you don't specify otherwise. (See
-    ``primary_key`` in ``General field options`` above.)
 
-``BooleanField``
+    first_name = models.CharField(maxlength=30)
-    A true/false field.
 
-    The admin represents this as a checkbox.
+``ForeignKey``, ``ManyToManyField`` and ``OneToOneField`` require the first
+argument to be a model class, so use the ``verbose_name`` keyword argument::
 
-``CharField``
+    poll = models.ForeignKey(Poll, verbose_name="the related poll")
-    A string field, for small- to large-sized strings.
+    sites = models.ManyToManyField(Site, verbose_name="list of sites")
+    place = models.OneToOneField(Place, verbose_name="related place")
 
-    For large amounts of text, use ``TextField``.
+Convention is not to capitalize the first letter of the ``verbose_name``.
-
+Django will automatically capitalize the first letter where it needs to.
-    The admin represents this as an ``<input type="text">`` (a single-line input).
-
-    ``CharField`` has an extra required argument, ``maxlength``, the maximum
-    length (in characters) of the field. The maxlength is enforced at the
-    database level and in Django's validation.
-
-``CommaSeparatedIntegerField``
-    A field of integers separated by commas. As in ``CharField``, the
-    ``maxlength`` argument is required.
-
-``DateField``
-    A date field. Has a few extra optional arguments:
-
-        ======================  ===================================================
-        Argument                Description
-        ======================  ===================================================
-        ``auto_now``            Automatically set the field to now every time the
-                                object is saved. Useful for "last-modified"
-                                timestamps.
-
-        ``auto_now_add``        Automatically set the field to now when the object
-                                is first created. Useful for creation of
-                                timestamps.
-        ======================  ===================================================
-
-    The admin represents this as an ``<input type="text">`` with a JavaScript
-    calendar and a shortcut for "Today."
-
-``DateTimeField``
-    A date and time field. Takes the same extra options as ``DateField``.
-
-    The admin represents this as two ``<input type="text">`` fields, with
-    JavaScript shortcuts.
-
-``EmailField``
-    A ``CharField`` that checks that the value is a valid e-mail address.
-    This doesn't accept ``maxlength``.
-
-``FileField``
-    A file-upload field.
-
-    Has an extra required argument, ``upload_to``, a local filesystem path to
-    which files should be upload. This path may contain `strftime formatting`_,
-    which will be replaced by the date/time of the file upload (so that
-    uploaded files don't fill up the given directory).
-
-    The admin represents this as an ``<input type="file">`` (a file-upload widget).
-
-    Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few
-    steps:
-
-        1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the
-           full path to a directory where you'd like Django to store uploaded
-           files. (For performance, these files are not stored in the database.)
-           Define ``MEDIA_URL`` as the base public URL of that directory. Make
-           sure that this directory is writable by the Web server's user
-           account.
-
-        2. Add the ``FileField`` or ``ImageField`` to your model, making sure
-           to define the ``upload_to`` option to tell Django to which
-           subdirectory of ``MEDIA_ROOT`` it should upload files.
-
-        3. All that will be stored in your database is a path to the file
-           (relative to ``MEDIA_ROOT``). You'll must likely want to use the
-           convenience ``get_<fieldname>_url`` function provided by Django. For
-           example, if your ``ImageField`` is called ``mug_shot``, you can get
-           the absolute URL to your image in a template with ``{{
-           object.get_mug_shot_url }}``.
-
-    .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
-
-``FilePathField``
-    A field whose choices are limited to the filenames in a certain directory
-    on the filesystem. Has three special arguments, of which the first is
-    required:
-
-        ======================  ===================================================
-        Argument                Description
-        ======================  ===================================================
-        ``path``                Required. The absolute filesystem path to a
-                                directory from which this ``FilePathField`` should
-                                get its choices. Example: ``"/home/images"``.
-
-        ``match``               Optional. A regular expression, as a string, that
-                                ``FilePathField`` will use to filter filenames.
-                                Note that the regex will be applied to the
-                                base filename, not the full path. Example:
-                                ``"foo.*\.txt^"``, which will match a file called
-                                ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.
-
-        ``recursive``           Optional. Either ``True`` or ``False``. Default is
-                                ``False``. Specifies whether all subdirectories of
-                                ``path`` should be included.
-        ======================  ===================================================
-
-    Of course, these arguments can be used together.
-
-    The one potential gotcha is that ``match`` applies to the base filename,
-    not the full path. So, this example::
-
-        FilePathField(path="/home/images", match="foo.*", recursive=True)
-
-    ...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``
-    because the ``match`` applies to the base filename (``foo.gif`` and
-    ``bar.gif``).
-
-``FloatField``
-    A floating-point number. Has two **required** arguments:
-
-        ======================  ===================================================
-        Argument                Description
-        ======================  ===================================================
-        ``max_digits``          The maximum number of digits allowed in the number.
-
-        ``decimal_places``      The number of decimal places to store with the
-                                number.
-        ======================  ===================================================
-
-    For example, to store numbers up to 999 with a resolution of 2 decimal places,
-    you'd use::
-
-        models.FloatField(..., max_digits=5, decimal_places=2)
-
-    And to store numbers up to approximately one billion with a resolution of 10
-    decimal places::
-
-        models.FloatField(..., max_digits=19, decimal_places=10)
-
-    The admin represents this as an ``<input type="text">`` (a single-line input).
-
-``ImageField``
-    Like ``FileField``, but validates that the uploaded object is a valid
-    image. Has two extra optional arguments, ``height_field`` and
-    ``width_field``, which, if set, will be auto-populated with the height and
-    width of the image each time a model instance is saved.
-
-    Requires the `Python Imaging Library`_.
-
-    .. _Python Imaging Library: http://www.pythonware.com/products/pil/
-
-``IntegerField``
-    An integer.
-
-    The admin represents this as an ``<input type="text">`` (a single-line input).
-
-``IPAddressField``
-    An IP address, in string format (i.e. "24.124.1.30").
-
-    The admin represents this as an ``<input type="text">`` (a single-line input).
-
-``NullBooleanField``
-    Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this
-    instead of a ``BooleanField`` with ``null=True``.
-
-    The admin represents this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
-
-``PhoneNumberField``
-    A ``CharField`` that checks that the value is a valid U.S.A.-style phone
-    number (in the format ``XXX-XXX-XXXX``).
-
-``PositiveIntegerField``
-    Like an ``IntegerField``, but must be positive.
-
-``PositiveSmallIntegerField``
-    Like a ``PositiveIntegerField``, but only allows values under a certain
-    (database-dependent) point.
-
-``SlugField``
-    "Slug" is a newspaper term. A slug is a short label for something,
-    containing only letters, numbers, underscores or hyphens. They're generally
-    used in URLs.
-
-    In the Django development version, you can specify ``maxlength``. If
-    ``maxlength`` is not specified, Django will use a default length of 50. In
-    previous Django versions, there's no way to override the length of 50.
-
-    Implies ``db_index=True``.
-
-    Accepts an extra option, ``prepopulate_from``, which is a list of fields
-    from which to auto-populate the slug, via JavaScript, in the object's admin
-    form::
-
-        models.SlugField(prepopulate_from=("pre_name", "name"))
-
-    ``prepopulate_from`` doesn't accept DateTimeFields.
-
-    The admin represents ``SlugField`` as an ``<input type="text">`` (a
-    single-line input).
-
-``SmallIntegerField``
-    Like an ``IntegerField``, but only allows values under a certain
-    (database-dependent) point.
-
-``TextField``
-    A large text field.
-
-    The admin represents this as a ``<textarea>`` (a multi-line input).
-
-``TimeField``
-    A time. Accepts the same auto-population options as ``DateField`` and
-    ``DateTimeField``.
-
-    The admin represents this as an ``<input type="text">`` with some
-    JavaScript shortcuts.
-
-``URLField``
-    A field for a URL. If the ``verify_exists`` option is ``True`` (default),
-    the URL given will be checked for existence (i.e., the URL actually loads
-    and doesn't give a 404 response).
-
-    The admin represents this as an ``<input type="text">`` (a single-line input).
-
-``USStateField``
-    A two-letter U.S. state abbreviation.
-
-    The admin represents this as an ``<input type="text">`` (a single-line input).
-
-``XMLField``
-    A ``TextField`` that checks that the value is valid XML that matches a
-    given schema. Takes one required argument, ``schema_path``, which is the
-    filesystem path to a RelaxNG_ schema against which to validate the field.
-
-    .. _RelaxNG: http://www.relaxng.org/
 
 Relationships
 -------------
@@ -496,7 +642,7 @@ following definitions::
         city = models.ForeignKey(City)
 
 To create a recursive relationship -- an object that has a many-to-one
-relationship with itself -- use ``models.ForeignKey("self")``.
+relationship with itself -- use ``models.ForeignKey('self')``.
 
 If you need to create a relationship on a model that has not yet been defined,
 you can use the name of the model, rather than the model object itself::
@@ -749,20 +895,22 @@ See the `One-to-one relationship model example`_ for a full example.
 Meta options
 ============
 
-Give your model metadata by using an inner ``"class Meta"``, like so::
+Give your model metadata by using an inner ``class Meta``, like so::
 
     class Foo(models.Model):
         bar = models.CharField(maxlength=30)
-        # ...
+
         class Meta:
             # ...
 
-Model metadata is "anything that's not a field" -- ordering options, etc.
+Model metadata is "anything that's not a field", such as ordering options, etc.
 
 Here's a list of all possible ``Meta`` options. No options are required. Adding
 ``class Meta`` to a model is completely optional.
 
 ``db_table``
+------------
+
 The name of the database table to use for the module::
 
     db_table = "pizza_orders"
@@ -774,6 +922,8 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 that's OK. Django quotes column and table names behind the scenes.
 
 ``get_latest_by``
+-----------------
+
 The name of a ``DateField`` or ``DateTimeField``. If given, the module will
 have a ``get_latest()`` function that fetches the "latest" object according
 to that field::
@@ -784,14 +934,9 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 
 .. _Getting the "latest" object: http://www.djangoproject.com/documentation/models/get_latest/
 
-``module_name``
-    The name of the module::
-
-        module_name = "pizza_orders"
-
-    If this isn't given, Django will use a lowercase version of the class name.
-
 ``order_with_respect_to``
+-------------------------
+
 Marks this object as "orderable" with respect to the given field. This is
 almost always used with related objects to allow them to be ordered with
 respect to a parent object. For example, if a ``PizzaToppping`` relates to
@@ -799,9 +944,11 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 
     order_with_respect_to = 'pizza'
 
-    to allow the toppings to be ordered with respect to the associated pizza.
+...to allow the toppings to be ordered with respect to the associated pizza.
 
 ``ordering``
+------------
+
 The default ordering for the object, for use when obtaining lists of objects::
 
     ordering = ['-order_date']
@@ -830,6 +977,8 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 .. _Specifying ordering: http://www.djangoproject.com/documentation/models/ordering/
 
 ``permissions``
+---------------
+
 Extra permissions to enter into the permissions table when creating this
 object. Add, delete and change permissions are automatically created for
 each object that has ``admin`` set. This example specifies an extra
@@ -841,6 +990,8 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 ``(permission_code, human_readable_permission_name)``.
 
 ``unique_together``
+-------------------
+
 Sets of field names that, taken together, must be unique::
 
     unique_together = (("driver", "restaurant"),)
@@ -851,6 +1002,8 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 ``CREATE TABLE`` statement).
 
 ``verbose_name``
+----------------
+
 A human-readable name for the object, singular::
 
     verbose_name = "pizza"
@@ -859,12 +1012,29 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
 ``CamelCase`` becomes ``camel case``.
 
 ``verbose_name_plural``
+-----------------------
+
 The plural name for the object::
 
     verbose_name_plural = "stories"
 
 If this isn't given, Django will use ``verbose_name + "s"``.
 
+
+
+========================================
+THE REST OF THIS HAS NOT YET BEEN EDITED
+========================================
+
+
+
+Table names
+===========
+
+Automatic primary key fields
+============================
+
+
 Admin options
 =============