Made a bunch of doc improvements

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

4 files changed, 857 insertions, 1039 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 193cbf2b22..2a41e9b373 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -2,7 +2,11 @@
 Database API reference
 ======================
 
-XXX INTRO HERE XXX
+Once you've created your `data models`_, you'll need to lookup data from the
+database.  This document explains the database abstraction API derived from the
+models, and how to create, retrieve, and update objects.
+
+.. _`data models`: http://www.djangoproject.com/documentation/model_api/
 
 Throughout this reference, we'll refer to the following Poll application::
 
@@ -287,6 +291,18 @@ For example::
 
     SELECT * FROM polls_polls WHERE question LIKE 'Who%' AND id IN (3, 4, 5, 20);
 
+Changing objects
+================
+
+Once you've retrieved an object from the database using any of the above 
+options, changing it is extremely easy.  Make changes directly to the
+objects fields, then call the object's ``save()`` method::
+
+    >>> p = polls.get_object(id__exact=15)
+    >>> p.slug = "new_slug"
+    >>> p.pub_date = datetime.datetime.now()
+    >>> p.save()
+
 Creating new objects
 ====================
 
diff --git a/docs/faq.txt b/docs/faq.txt
index fdcc6789bf..e58fa03ea1 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -2,16 +2,20 @@
 Django FAQ
 ==========
 
-The admin site is ugly!  How can I change it?
----------------------------------------------
+General questions
+=================
 
-We think it's very purty, but if you don't agree you can modify the admin site's
-presentation by editing the CSS stylesheet and/or associated image files.  The 
-site is built using semantic HTML, so any changes you'd like to make should be
-possible by editing the CSS stylesheet.  We've got a `guide to the CSS used 
-in the admin`_ to get you started.
+Why does this project exist?
+----------------------------
+
+Django grew from a very practical need: in our fast-paced newsroom, we often
+have only a matter of hours to take a complicated web application from
+concept to public launch.  Django was designed to not only allow us to
+build web applications quickly, but to allow us to build them right.
 
-.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/FIXME/
+Django would not be possible without a whole host of open-source projects --
+Apache, Python, and PostgresSQL to name a few -- and we're thrilled to be
+able to give something back to the open source community.
 
 How do you pronounce "Django"?
 ------------------------------
@@ -27,23 +31,66 @@ We've been using Django for almost two years.  Sites built on Django have
 weathered traffic spikes of over one million hits an hour, and at least
 one slashdotting.  Yes; it's quite stable.
 
+Does Django scale?
+------------------
+
+Yes.  Compared to development time, hardware is cheap, and so Django is
+designed to take advantage of as much hardware as you can throw at it.
+Django ships with clean separation of the database layer from the 
+application layer and a simple yet powerful `cache framework`_.
+
+.. _`cache framework`: http://www.djangoproject.com/documentation/cache/
+
 Who's behind this?
 ------------------
 
 `Adrian Holovaty`_
-    XXX
-    
+    Adrian is a gypsy-jazz virtuoso, an amateur Beatles historian and a proud
+    Chicagoan. He's also a pretty decent programmer, with a knack for whipping
+    data into shape and putting it to work for the good of his fellow man.
+    Adrian is the lead developer at World Online and the man behind the code at
+    chicagocrime.org.
+
 `Simon Willison`_
     XXX
 
 `Jacob Kaplan-Moss`_
-    XXX
+    Jacob is a whipper-snapper from California who spends equal time coding and
+    cooking. He does Web development for World Online and actively hacks on
+    various cool side projects. He's contributed to the Python-ObjC bindings and
+    was the first guy to figure out how to write Tivo apps in Python. Lately
+    he's been messing with Python on the PSP.
 
-`Wilson Miner`_.
-    XXX
-    
+`Wilson Miner`_
+    Wilson's design-fu makes us all look like rock stars. When not sneaking
+    into apartment complex swimming pools  he is the Commercial Development
+    Director for World Online, which means he makes the money that pays all our
+    paychecks.  
+        
 .. _`Adrian Holovaty`: http://www.holovaty.com/
 .. _`Simon Willison`: http://simon.incutio.com/
 .. _`Jacob Kaplan-Moss`: http://www.jacobian.org/
 .. _`Wilson Miner`: http://www.wilsonminer.com/live/
 
+Using Django
+============
+
+How do I get started?
+---------------------
+
+...
+
+The admin interface
+===================
+
+The admin site is ugly!  How can I change it?
+---------------------------------------------
+
+We think it's very purty, but if you don't agree you can modify the admin site's
+presentation by editing the CSS stylesheet and/or associated image files.  The 
+site is built using semantic HTML, so any changes you'd like to make should be
+possible by editing the CSS stylesheet.  We've got a `guide to the CSS used 
+in the admin`_ to get you started.
+
+.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/
+
diff --git a/docs/model-api.txt b/docs/model-api.txt
index b794da2678..5cfd410efd 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -2,141 +2,117 @@
 Model reference
 ===============
 
-XXX INTRO XXX
+Django's models are the bread and butter of the framework.  There's a huge 
+array of options available to you when defining your data models; this 
+document explains all of them.
 
 Options for models
 ==================
 
-A list of all possible options for a model object follows.  Although there's a wide
-array of possible options, only ``fields`` is required.
+A list of all possible options for a model object follows.  Although there's a
+wide array of possible options, only ``fields`` is required.
 
 ``admin``
----------
-
-A ``meta.Admin`` object; see `Admin options`_.  If this field isn't given,
-the object will not have an admin interface.
-
+    A ``meta.Admin`` object; see `Admin options`_.  If this field isn't given,
+    the object will not have an admin interface.
+    
 ``db_table``
-------------
-
-The name of the database table to use for the module::
-
-    db_table = "pizza_orders"
+    The name of the database table to use for the module::
+    
+        db_table = "pizza_orders"
+        
+    If not given, this will use ``app_label + '_' + module_name``.
     
-If not given, this will use ``app_label + '_' + module_name``.
-
 ``exceptions``
---------------
-
-Names of extra exception subclasses to include in the generated module.
-These exceptions are available from instance methods and from module-level
-methods::
+    Names of extra exception subclasses to include in the generated module.
+    These exceptions are available from instance methods and from module-level
+    methods::
+        
+        exceptions = ("DisgustingToppingsException", "BurntCrust")
     
-    exceptions = ("DisgustingToppingsException", "BurntCrust")
-
 ``fields``
-----------
-
-A list of field objects; see `Field objects`_.  For example::
-
-    fields = (
-        meta.CharField('customer_name', 'customer name', maxlength=15),
-        meta.BooleanField('use_extra_cheese', 'use extra cheese'),
-        meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES),
-        ...
-    )
+    A list of field objects; see `Field objects`_.  For example::
     
+        fields = (
+            meta.CharField('customer_name', 'customer name', maxlength=15),
+            meta.BooleanField('use_extra_cheese', 'use extra cheese'),
+            meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES),
+            ...
+        )
+        
 ``get_latest_by``
------------------
-
-The name of a date or datetime field; if given, the module will have a
-``get_latest()`` function which fetches the "latest" object in terms of
-that field::
-
-    get_latest_by = "order_date"
-
+    The name of a date or datetime field; if given, the module will have a
+    ``get_latest()`` function which fetches the "latest" object in terms of
+    that field::
+    
+        get_latest_by = "order_date"
+    
 ``module_constants``
---------------------
-
-A dict of name/values to use as extra module-level constants::
-
-    module_constants = {
-        'MEAT_TYPE_PEPPERONI' : 1,
-        'MEAT_TYPE_SAUSAGE' : 2,
-    }
-
+    A dict of name/values to use as extra module-level constants::
+    
+        module_constants = {
+            'MEAT_TYPE_PEPPERONI' : 1,
+            'MEAT_TYPE_SAUSAGE' : 2,
+        }
+    
 ``module_name``
----------------
-
-The name of the module::
-
-    module_name = "pizza_orders"
+    The name of the module::
+    
+        module_name = "pizza_orders"
+        
+    If not given this will use a lowercased version of the class name.
     
-If not given this will use a lowercased 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
-a ``Pizza`` object, you might use::
-
-    order_with_respect_to = 'pizza_id'
-
-to allow the toppings to be ordered with respect to the associated pizza.
-
+    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
+    a ``Pizza`` object, you might use::
+    
+        order_with_respect_to = 'pizza_id'
+    
+    to allow the toppings to be ordered with respect to the associated pizza.
+    
 ``ordering``
-------------
-
-The default ordering for tho object::
-
-    ordering = (('order_date', 'DESC'),)
+    The default ordering for tho object::
+    
+        ordering = (('order_date', 'DESC'),)
+        
+    This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)``
+    where ordering_type is either ``"ASC"`` or ``"DESC"``.  You may also use the
+    magic ``(None, "RANDOM")`` ordering tuple for random ordering.
     
-This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)``
-where ordering_type is either ``"ASC"`` or ``"DESC"``.  You may also use the
-magic ``(None, "RANDOM")`` ordering tuple for random ordering.
-
 ``permissions``
----------------
-
-Extra permissions to enter into the permissions table when creating this
-object.  A add, delete, and change permission is automatically created for
-each object; this option specifies extra permissions::
-
-    permissions = (("may_delivier_pizzas", "Can deliver pizzas"),)
+    Extra permissions to enter into the permissions table when creating this
+    object.  A add, delete, and change permission is automatically created for
+    each object; this option specifies extra permissions::
+    
+        permissions = (("may_delivier_pizzas", "Can deliver pizzas"),)
+        
+    This is a list of 2-tuples of 
+    ``(permission_code, human_readable_permission_name)``.
     
-This is a list of 2-tuples of 
-``(permission_code, human_readable_permission_name)``.
-
 ``unique_together``
--------------------
-
-Sets of field names that, taken together, must be unique::
-
-    unique_together = (("driver_id", "restaurant_id"),)
+    Sets of field names that, taken together, must be unique::
+    
+        unique_together = (("driver_id", "restaurant_id"),)
+        
+    This is a list of lists of fields that must be unique when considered
+    together.
     
-This is a list of lists of fields that must be unique when considered
-together.
-
 ``verbose_name``
-----------------
-
-A human-readable name for the object, singular::
-
-    verbose_name = "pizza"
-
-If not given, this will use a munged version of the class name:
-``CamelCase`` becomes ``camel case``.
-
+    A human-readable name for the object, singular::
+    
+        verbose_name = "pizza"
+    
+    If not given, this will use a munged version of the class name:
+    ``CamelCase`` becomes ``camel case``.
+    
 ``verbose_name_plural``
------------------------
-
-The plural name for the object::
-
-    verbose_name_plural = "stories"
-
-If not given, ``verbose_name + "s"`` will automatically be used.
+    The plural name for the object::
+    
+        verbose_name_plural = "stories"
+    
+    If not given, ``verbose_name + "s"`` will automatically be used.
     
 Field objects
 =============
@@ -249,256 +225,91 @@ options that are common to all field types.  These options are:
 
 Field Types
 -----------
-
+    
 ``AutoField``
-`````````````
-
-An ``IntegerField`` that automatically increments.  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.  That automatically added field is::
-
-    meta.AutoField('id', 'ID', primary_key=True)
-
+    An ``IntegerField`` that automatically increments.  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.  That automatically added field is::
+    
+        meta.AutoField('id', 'ID', primary_key=True)
+    
 ``BooleanField``
-````````````````
-
-A true/false field.
-
+    A true/false field.
+    
 ``CharField``
-`````````````
-
-A text field. These are displayed in the admin as single-line text inputs, so 
-for large amounts of text use a ``TextField``.
-
-``CharField``s have an extra required argument: ``maxlength``; the maximum 
-length (in characters) of the field.
-
+    A text field. These are displayed in the admin as single-line text inputs, so 
+    for large amounts of text use a ``TextField``.
+    
+    ``CharField``s have an extra required argument: ``maxlength``; the maximum 
+    length (in characters) of the field.
+    
 ``CommaSeparatedIntegerField``
-``````````````````````````````
-
-A field of integers separated by commas.
-
+    A field of integers separated by commas.
+    
 ``DateField``
-`````````````
-
-A, um, date field.  Has a few extra optional options:
-
-    ======================  ===================================================
-    Option                  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 timestamps.
-    ======================  ===================================================
-
+    A, um, date field.  Has a few extra optional options:
+    
+        ======================  ===================================================
+        Option                  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 timestamps.
+        ======================  ===================================================
+    
 ``DateTimeField``
-`````````````````
-
-A date and time field.  Takes the same extra options as ``DateField``.
-
-
+    A date and time field.  Takes the same extra options as ``DateField``.
+    
+    
 ``EmailField``
-``````````````
-
-A ``CharField`` that checks that the value is a valid email address.  Because
-validating email addresses can be tricky, this is a pretty loose test.
-
+    A ``CharField`` that checks that the value is a valid email address.  Because
+    validating email addresses can be tricky, this is a pretty loose test.
+    
 ``FileField``
-`````````````
-
-A file-upload field.  Takes on additional option, ``upload_to`` which is
-a path to upload the file to.  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).
-
-.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
-
+    A file-upload field.  Takes on additional option, ``upload_to`` which is
+    a path to upload the file to.  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).
+    
+    .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
+    
 ``FloatField``
-``````````````
-
-A floating-point number.  Has two additional required options:
-
-    ======================  ===================================================
-    Option                  Description
-    ======================  ===================================================
-    ``max_digits``          The maximum number of digits allowed in the number.
+    A floating-point number.  Has two additional required options:
     
-    ``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::
-
-    meta.FloatField(..., max_digits=5, decimal_places=2)
-
-And to store numbers up to one million with a resolution of 10 decimal places::
-
-    meta.FloatField(..., max_digits=19, decimal_places=10)
-
-``ForeignKey``
-``````````````
-
-A many-to-one relationship to the primary key in another object.  So, to give a
-``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are 
-many toppings on a pizza)::
-
-    meta.ForeignKey(Pizza)
+        ======================  ===================================================
+        Option                  Description
+        ======================  ===================================================
+        ``max_digits``          The maximum number of digits allowed in the number.
+        
+        ``decimal_places``      The number of decimal places to store with the
+                                number
+        ======================  ===================================================
     
-This is equivalent to (but much clearer than)::
-
-    meta.IntegerField('pizza_id', 'pizza', rel=meta.ManyToOne(Pizza, 'pizza', 'id'))
+    For example, to store numbers up to 999 with a resolution of 2 decimal places,
+    you'd use::
     
-``ForeignKey`` fields take all the arguments of ``ManyToOne`` relations (see
-Relationships_, below for what those arguments are), plus the following extra
-options:
-
-    ======================  ===================================================
-    Option                  Description
-    ======================  ===================================================
-    ``to_field``            The field on the related object that the relation
-                            is to.  This is almost always ``id``, but if the
-                            PK on the other object is named something 
-                            different, this is how to indicate that.
-                            
-    ``rel_name``            The name of the relation.  In the above exmaple,
-                            this would default to 'pizza' (so that the 
-                            ``Toppings`` object would have a ``get_pizza()``
-                            function; if you set ``rel_name`` to "pie", then
-                            the function would be called ``get_pie()`` and the
-                            field name would be ``pie_id``.
-    ======================  ===================================================
-
+        meta.FloatField(..., max_digits=5, decimal_places=2)
     
-``ImageField``
-``````````````
-
-Like a ``FieldField``, 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.
-
-``IntegerField``
-````````````````
-
-An integer, surprisingly.
-
-``IPAddressField``
-``````````````````
-
-An IP address, in string format (i.e. "24.124.1.30").
-
-``ManyToManyField``
-```````````````````
-
-XXX document once Adrian reworks this XXX
-
-``NullBooleanField``
-````````````````````
-
-Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this
-instead of a ``BooleanField`` with ``null=True`` .
-
-``PhoneNumberField``
-````````````````````
-
-Validates that the value is a valid phone number.
-
-``PositiveIntegerField``
-````````````````````````
-
-Like an ``IntegerField``, but must be positive.
-
-``PositiveSmallIntegerField``
-`````````````````````````````
-
-Like a ``PositiveIntegerField``, but only allows values below 32767.
-
-
-``SlugField``
-`````````````
-
-A "slug" suitable for parts of a URL; only allows alpha-numeric characters and
-underscores.  
-
-Implies ``maxlength=50`` and ``db_index=True``.
-
-Accepts an extra option, ``prepopulate_from`` which is a list of fields from
-which to auto-populate the slug.
-
-``SmallIntegerField``
-`````````````````````
-
-Like an ``IntegerField``, but must be between -32768 and 32767.
-
-``TextField``
-`````````````
-
-A large text field (``<textarea>`` in HTML).
-
-``TimeField``
-`````````````
-
-A time.  Accepts the same auto-population options as ``DateField`` and
-``DateTimeField``.
-
-``URLField``
-````````````
-
-A field for a URL.  If the ``verify_exists`` option is ``True``, the URL given
-will be checked for existence (i.e. actually loads and doesn't give a 404 
-response).
-
-``USStateField``
-````````````````
-
-A US state.
-
-``XMLField``
-````````````
-
-A field containing XML.  Takes one required argument, ``schema_path`` which
-is the path to a RelaxNG_ scheme against which to validate the field.
-
-.. _RelaxNG: http://www.relaxng.org/
-
-Relationships
-=============
-
-The ``rel`` option for a field marks that field as being a relationship to
-another object.  For the most common cases, using ``ForeignKey`` or
-``ManyToManyField`` is best; these "shortcuts" encapsulate best practices
-in database design (i.e. using integer foreign keys into another table's
-primary key).  If you do need to explicitly create a relation, these relation
-objects should be used as the value of the ``rel`` attribute.  Also, all
-the options for ``ManyToOne`` are allowed as options for ``ForeignKey``, 
-and the same goes for ``ManyToMany`` and ``ManyToManyField``.
-
-``ManyToOne``
--------------
-
-Signifies a many-to-one relation: if a ``Pizza`` can have many ``Topping``s,
-then the ``Topping`` object should have a ``ManyToOne`` relation to ``Pizza``.
-
-The three positional arguments to ``ManyToMany`` are:
-
-    * The class to relate to (i.e. ``Pizza`` or ``core.Site``).
+    And to store numbers up to one million with a resolution of 10 decimal places::
     
-    * The name of the relation (i.e. ``pizza``, or ``site``); this is used in
-      the generated functions for managing that relationship (i.e. 
-      ``get_pizza`` and ``get_site``).
-      
-    * The name of the field the relationship "points" to.  In most cases this
-      will be "id", but if the other object's PK isn't named "id", this
-      must match the PK field name.
-      
-The keyword arguments accepted by ``ManyToOne`` are:
-
-    =======================  ==================================================
+        meta.FloatField(..., max_digits=19, decimal_places=10)
+    
+``ForeignKey``
+    A many-to-one relationship to the primary key in another object.  So, to give a
+    ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are 
+    many toppings on a pizza)::
+    
+        meta.ForeignKey(Pizza)
+                
+    ``ForeignKey`` fields take a large number of options for defining how the 
+    relationship should work:
+    
+    ======================   ===================================================
     Option                   Description
-    =======================  ==================================================
+    ======================   ===================================================
     ``edit_inline``          If ``True``, this related object is edited 
                              "inline" on the related object's page.  This means
                              that the object will not have its own admin 
@@ -511,7 +322,7 @@ The keyword arguments accepted by ``ManyToOne`` are:
                              ``meta.STACKED``.
                              
     ``limit_choices_to``     A dictionary of lookup arguments and values (see
-                             the `Dictionary API reference`_) to limit choices
+                             the `Database API reference`_) to limit choices
                              of this object to.  Use this along with 
                              ``meta.LazyDate`` to limit choices of objects
                              by date, for example::
@@ -524,8 +335,6 @@ The keyword arguments accepted by ``ManyToOne`` are:
                              
                              Not compatible with ``edit_inline``.
     
-    ``lookup_overrides``     XXX FIXME XXX
-    
     ``max_num_in_admin``     For inline-edited objects, this is the maximum
                              number of related objects to display in the admin.
                              Thus, if a pizza could only have up to 10 
@@ -556,6 +365,13 @@ The keyword arguments accepted by ``ManyToOne`` are:
                              rows to make a menu practical.
                              
                              Not used with ``edit_inline``.
+                             
+    ``rel_name``             The name of the relation.  In the above exmaple,
+                             this would default to 'pizza' (so that the 
+                             ``Toppings`` object would have a ``get_pizza()``
+                             function; if you set ``rel_name`` to "pie", then
+                             the function would be called ``get_pie()`` and the
+                             field name would be ``pie_id``.
     
     ``related_name``         The name to use for the relation from the related
                              object back to this one.  For example, when if
@@ -596,37 +412,74 @@ The keyword arguments accepted by ``ManyToOne`` are:
                              which would give the category objects methods 
                              named ``get_primary_story_list()`` and 
                              ``get_secondary_story_list()``.
+                             
+    ``to_field``             The field on the related object that the relation
+                             is to.  This is almost always ``id``, but if the
+                             PK on the other object is named something 
+                             different, this is how to indicate that.
     =======================  ==================================================
 
-.. _`Dictionary API reference`: http://www.djangoproject.com/FIXME/
-
-``ManyToMany``
---------------
-
-XXX will this still exist given the changes to ManyToManyField? XXX
-
-``OneToOne``
-------------
-
-Signifies a one-to-one relationship.  This is most useful on the primary key
-of an object when that object "extends" another object in some way.  
-
-For example, if you are building a database of "places", you would build pretty
-standard stuff like address, phone number, etc. in the database.  If you then
-wanted to build a database of restaurants on top of the places, instead of
-repeating yourself and replicating those fields in the restaurants object, you
-could make ``Restaurant`` have a ``OneToOne`` relation to ``Place`` (since
-a restaurant "is-a" place).
-
-This has a few repercussions in the admin interface:
-
-    * No selection interface is displayed on ``Restaurant`` pages; there will
-      be one (and only one) ``Restaurant`` for each place.
-      
-    * On the ``Restaurant`` change list, every single ``Place`` -- weather it
-      has an associated ``Restaurant`` or not -- will be displayed.  Adding
-      a ``Restaurant`` to a ``Place`` just means filling out the required
-      ``Restaurant`` fields.
+.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/    
+        
+``ImageField``
+    Like a ``FieldField``, 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.
+    
+``IntegerField``
+    An integer, surprisingly.
+    
+``IPAddressField``
+    An IP address, in string format (i.e. "24.124.1.30").
+    
+``ManyToManyField``
+    XXX document once Adrian reworks this XXX
+    
+``NullBooleanField``
+    Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this
+    instead of a ``BooleanField`` with ``null=True`` .
+    
+``PhoneNumberField``
+    Validates that the value is a valid phone number.
+    
+``PositiveIntegerField``
+    Like an ``IntegerField``, but must be positive.
+    
+``PositiveSmallIntegerField``
+    Like a ``PositiveIntegerField``, but only allows values below 32767.
+    
+``SlugField``
+    A "slug" suitable for parts of a URL; only allows alpha-numeric characters and
+    underscores.  
+    
+    Implies ``maxlength=50`` and ``db_index=True``.
+    
+    Accepts an extra option, ``prepopulate_from`` which is a list of fields from
+    which to auto-populate the slug.
+    
+``SmallIntegerField``
+    Like an ``IntegerField``, but must be between -32768 and 32767.
+    
+``TextField``
+    A large text field (``<textarea>`` in HTML).
+    
+``TimeField``
+    A time.  Accepts the same auto-population options as ``DateField`` and
+    ``DateTimeField``.
+    
+``URLField``
+    A field for a URL.  If the ``verify_exists`` option is ``True``, the URL given
+    will be checked for existence (i.e. actually loads and doesn't give a 404 
+    response).
+    
+``USStateField``
+    A US state.
+    
+``XMLField``
+    A field containing XML.  Takes one required argument, ``schema_path`` which
+    is the path to a RelaxNG_ scheme against which to validate the field.
+    
+    .. _RelaxNG: http://www.relaxng.org/
 
 Admin options
 =============
@@ -635,126 +488,108 @@ The ``admin`` field in the model tells Django how to construct the admin
 interface for the object.  The field is an instance of the ``meta.Admin`` 
 object, which has the following options (of which only ``fields`` is required):
 
-``date_hierarchy``
-------------------
-
-To allow filtering of objects in the admin by date, set ``date_hierarchy``
-to the name of the field to filter by::
-
-    date_hierarchy = 'order_date'
-
+``date_hierarchy``    
+    To allow filtering of objects in the admin by date, set ``date_hierarchy``
+    to the name of the field to filter by::
+    
+        date_hierarchy = 'order_date'
+    
 ``fields``
-----------
-
-A list of fieldsets to display on the admin page.  Each fieldset is a 2-tuple:
-``(name, field_options)``.  The ``name`` is a string to name the field set,
-and ``field_options`` is a dictionary of information about the fields to be 
-displayed in that fieldset.  This dictionary has the following keys:
-
-    ``fields``
-        A tuple of field names to display in this fieldset.  To display
-        multiple fields on the same line, wrap those fields in their
-        own tuple.
-        
-        This key is required in the dict.
-        
-    ``classes``
-        Extra CSS classes to apply to the fieldset.  This is a simple
-        string; you can apply multiple classes by separating them with
-        spaces.
-        
-        Two useful classes defined by the default stylesheet are ``collapse``
-        and ``wide``.  Fieldsets with the ``collapse`` style will be 
-        initially collapsed in the admin and replaced with a small "click
-        to expand" link.  Fieldsets with the ``wide`` style will be given
-        extra horizontal space.
+    A list of fieldsets to display on the admin page.  Each fieldset is a 2-tuple:
+    ``(name, field_options)``.  The ``name`` is a string to name the field set,
+    and ``field_options`` is a dictionary of information about the fields to be 
+    displayed in that fieldset.  This dictionary has the following keys:
+    
+        ``fields``
+            A tuple of field names to display in this fieldset.  To display
+            multiple fields on the same line, wrap those fields in their
+            own tuple.
             
-For example (taken from the ``core.flatfiles`` model)::
-
-    fields = (
-        (None, {
-            'fields': ('url', 'title', 'content', 'sites')
-        }),
-        ('Advanced options', {
-            'classes': 'collapse', 
-            'fields' : ('enable_comments', 'registration_required', 'template_name')
-        }),
-    ),
+            This key is required in the dict.
+            
+        ``classes``
+            Extra CSS classes to apply to the fieldset.  This is a simple
+            string; you can apply multiple classes by separating them with
+            spaces.
+            
+            Two useful classes defined by the default stylesheet are ``collapse``
+            and ``wide``.  Fieldsets with the ``collapse`` style will be 
+            initially collapsed in the admin and replaced with a small "click
+            to expand" link.  Fieldsets with the ``wide`` style will be given
+            extra horizontal space.
+                
+    For example (taken from the ``core.flatfiles`` model)::
     
-results in an admin that looks like:
-
-    .. image:: images/flatfiles_admin.png
+        fields = (
+            (None, {
+                'fields': ('url', 'title', 'content', 'sites')
+            }),
+            ('Advanced options', {
+                'classes': 'collapse', 
+                'fields' : ('enable_comments', 'registration_required', 'template_name')
+            }),
+        ),
         
+    results in an admin that looks like:
+    
+        .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
+            
 ``js``
-------
-
-Extra JavaScript files to link into the admin screen.  This can be used to
-tweak a given type of admin page in JS or to provide "quick links" to fill
-in default values for certain fields.
-
+    Extra JavaScript files to link into the admin screen.  This can be used to
+    tweak a given type of admin page in JS or to provide "quick links" to fill
+    in default values for certain fields.
+    
 ``list_display``
-----------------
-
-List of fields to display on the list page in the admin.
-
-There are a few special cases that do other things besides displaying the
-contents of the given fields:
-
-    * If the field given has a relationship, that relationship is 
-      followed and the ``repr()`` of the related object is displayed.
-      
-    * If the field is a ``BooleanField``, a "on" or "off" icon will
-      be displayed instead of ``True`` or ``False``.
-      
-    * If the field name given does not exist, a function of the model
-      will be searched for and called if present.  This function
-      should have a ``short_description`` attribute that will be
-      used as the header for the field.
-      
-See the exmaple below.
-
+    List of fields to display on the list page in the admin.
+    
+    There are a few special cases that do other things besides displaying the
+    contents of the given fields:
+    
+        * If the field given has a relationship, that relationship is 
+          followed and the ``repr()`` of the related object is displayed.
+          
+        * If the field is a ``BooleanField``, a "on" or "off" icon will
+          be displayed instead of ``True`` or ``False``.
+          
+        * If the field name given does not exist, a function of the model
+          will be searched for and called if present.  This function
+          should have a ``short_description`` attribute that will be
+          used as the header for the field.
+          
+    See the exmaple below.
+    
 ``list_filter``
----------------
-
-List of fields to filter by.  Each field should either be a ``BooleanField``
-or else a field with a ``ManyToOne`` relation.
-
-An example of how ``list_display`` and ``list_filter`` work (taken from
-the ``auth.user`` model)::
-
-    list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'),
-    list_filter = ('is_staff', 'is_superuser'),
+    List of fields to filter by.  Each field should either be a ``BooleanField``
+    or else a field with a ``ManyToOne`` relation.
     
-results in a admin that looks like:
-
-    .. image:: images/users_changelist.png
+    An example of how ``list_display`` and ``list_filter`` work (taken from
+    the ``auth.user`` model)::
+    
+        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'),
+        list_filter = ('is_staff', 'is_superuser'),
+        
+    results in a admin that looks like:
+    
+        .. image:: http://media.djangoproject.com/img/doc/users_changelist.png
+        
+    (This example also has ``search_fields`` defined; see below).
     
-(This example also has ``search_fields`` defined; see below).
-
 ``ordering``
-------------
-
-An ordering tuple (see the `Options for models`_, above) that gives a 
-different ordering for the admin change list.  If not given, the 
-model's default ordering will be used.
-
+    An ordering tuple (see the `Options for models`_, above) that gives a 
+    different ordering for the admin change list.  If not given, the 
+    model's default ordering will be used.
+    
 ``save_as``
------------
-
-Enables a "save as" feature on object pages.  Normally, objects have
-three save options: "Save", "Save and continue editing", and "Save
-and add another".   If ``save_as`` is ``True``, "Save and add another"
-will be replaced by a "Save as" button.
-
+    Enables a "save as" feature on object pages.  Normally, objects have
+    three save options: "Save", "Save and continue editing", and "Save
+    and add another".   If ``save_as`` is ``True``, "Save and add another"
+    will be replaced by a "Save as" button.
+    
 ``save_on_top``
----------------
-
-If this option is ``True``, object pages will have the save buttons
-across the top as well as at the bottom of the page.
-
+    If this option is ``True``, object pages will have the save buttons
+    across the top as well as at the bottom of the page.
+    
 ``search_fields``
------------------
-
-A list of fields to provide a text search for.  These fields should,
-obviously, be some kind of text field.
-
+    A list of fields to provide a text search for.  These fields should,
+    obviously, be some kind of text field.
+    
diff --git a/docs/templates.txt b/docs/templates.txt
index 72b863513c..3f680ca929 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -204,7 +204,8 @@ Using the built-in reference
 
 Since Django can be used to develop any sort of site, the tags, filters, and
 variables available will be different depending on the application.  To make it
-simple to figure out what's available in a given site.
+simple to figure out what's available in a given site your admin interface
+has a complete reference of all the template goodies available to you.
 
 This documentation is integrated into the administration interface for your
 sites and is divided into 4 sections: tags, filters, models, and views.  The
@@ -255,550 +256,469 @@ tags/filters.
 Built-in tag reference
 ----------------------
 
-block
-`````
-
-Define a block that can be overridden by child templates.  See `Template
-inheritance`_ for more information.
-
-comment
-```````
-
-Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
-
-cycle
-`````
-
-Cycle among the given strings each time this tag is encountered.
-
-Within a loop, cycles among the given strings each time through
-the loop::
-
-    {% for o in some_list %}
-        <tr class="{% cycle row1,row2 %}">
-            ...
-        </tr>
-    {% endfor %}
-
-Outside of a loop, give the values a unique name the first time you call it,
-then use that name each successive time through::
-
-        <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
-        <tr class="{% cycle rowcolors %}">...</tr>
-        <tr class="{% cycle rowcolors %}">...</tr>
-
-You can use any number of values, separated by commas. Make sure not to put
-spaces between the values -- only commas.
-
-debug
-`````
-
-Output a whole load of debugging information, including the current context and
-imported modules.
-
-extends
-```````
-
-Signal that this template extends a parent template.
-
-This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
-the literal value "base" as the name of the parent template to extend, or ``{%
-extends variable %}`` uses the value of ``variable`` as the name of the parent
-template to extend.
-
-See `Template inheritance`_ for more information.
-
-filter
-``````
-
-Filter the contents of the blog through variable filters.
-
-Filters can also be piped through each other, and they can have arguments --
-just like in variable syntax.
-
-Sample usage::
-
-    {% filter escape|lower %}
-        This text will be HTML-escaped, and will appear in all lowercase.
-    {% endfilter %}
-
-firstof
-```````
-
-Outputs the first variable passed that is not False.  Outputs nothing if all the
-passed variables are False.
-
-Sample usage::
-
-    {% firstof var1 var2 var3 %}
+``block``
+    Define a block that can be overridden by child templates.  See `Template
+    inheritance`_ for more information.
     
-This is equivalent to::
-
-    {% if var1 %}
-        {{ var1 }}
-    {% else %}{% if var2 %}
-        {{ var2 }}
-    {% else %}{% if var3 %}
-        {{ var3 }}
-    {% endif %}{% endif %}{% endif %}
+``comment``
+    Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
     
-but obviously much cleaner!
-
-for
-```
-
-Loop over each item in an array.  For example, to display a list of athletes
-given ``athlete_list``::
-
-    <ul>
-    {% for athlete in athlete_list %}
-        <li>{{ athlete.name }}</li>
-    {% endfor %}
-    </ul>
-
-You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
-
-The for loop sets a number of variables available within the loop:
-
-    ==========================  ================================================
-    Variable                    Description
-    ==========================  ================================================
-    ``forloop.counter``         The current iteration of the loop (1-indexed)
-    ``forloop.counter0``        The current iteration of the loop (0-indexed)
-    ``forloop.first``           True if this is the first time through the loop
-    ``forloop.last``            True if this is the last time through the loop
-    ``forloop.parentloop``      For nested loops, this is the loop "above" the
-                                current one
-    ==========================  ================================================
-
-if
-``
-
-The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
-exists, is not empty, and is not a false boolean value) the contents of the
-block are output::
-
-    {% if athlete_list %}
-        Number of athletes: {{ athlete_list|count }}
-    {% else %}
-        No athletes.
-    {% endif %}
-
-In the above, if ``athlete_list`` is not empty, the number of athletes will be
-displayed by the ``{{ athlete_list|count }}`` variable.
-
-As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
-will be displayed if the test fails.
-
-``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
-a given variable::
-
-    {% if not athlete_list %}
-        There are no athletes.
-    {% endif %}
+``cycle``
+    Cycle among the given strings each time this tag is encountered.
     
-    {% if athlete_list or coach_list %}
-        There are some athletes or some coaches.
-    {% endif %}
+    Within a loop, cycles among the given strings each time through
+    the loop::
     
-    {% if not athlete_list or coach_list %}
-        There are no athletes or there are some coaches (OK, so 
-        writing English translations of boolean logic sounds 
-        stupid; it's not my fault).
-    {% endif %}
-
-For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if`` 
-tags instead::
-
-    {% if athlete_list %}
-        {% if coach_list %}
-            Number of athletes: {{ athlete_list|count }}.
-            Number of coaches: {{ coach_list|count }}.
+        {% for o in some_list %}
+            <tr class="{% cycle row1,row2 %}">
+                ...
+            </tr>
+        {% endfor %}
+    
+    Outside of a loop, give the values a unique name the first time you call it,
+    then use that name each successive time through::
+    
+            <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
+            <tr class="{% cycle rowcolors %}">...</tr>
+            <tr class="{% cycle rowcolors %}">...</tr>
+    
+    You can use any number of values, separated by commas. Make sure not to put
+    spaces between the values -- only commas.
+    
+``debug``
+    Output a whole load of debugging information, including the current context and
+    imported modules.
+    
+``extends``
+    Signal that this template extends a parent template.
+    
+    This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
+    the literal value "base" as the name of the parent template to extend, or ``{%
+    extends variable %}`` uses the value of ``variable`` as the name of the parent
+    template to extend.
+    
+    See `Template inheritance`_ for more information.
+    
+``filter``
+    Filter the contents of the blog through variable filters.
+    
+    Filters can also be piped through each other, and they can have arguments --
+    just like in variable syntax.
+    
+    Sample usage::
+    
+        {% filter escape|lower %}
+            This text will be HTML-escaped, and will appear in all lowercase.
+        {% endfilter %}
+    
+``firstof``
+    Outputs the first variable passed that is not False.  Outputs nothing if all the
+    passed variables are False.
+    
+    Sample usage::
+    
+        {% firstof var1 var2 var3 %}
+        
+    This is equivalent to::
+    
+        {% if var1 %}
+            {{ var1 }}
+        {% else %}{% if var2 %}
+            {{ var2 }}
+        {% else %}{% if var3 %}
+            {{ var3 }}
+        {% endif %}{% endif %}{% endif %}
+        
+    but obviously much cleaner!
+    
+``for``
+    Loop over each item in an array.  For example, to display a list of athletes
+    given ``athlete_list``::
+    
+        <ul>
+        {% for athlete in athlete_list %}
+            <li>{{ athlete.name }}</li>
+        {% endfor %}
+        </ul>
+    
+    You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
+    
+    The for loop sets a number of variables available within the loop:
+    
+        ==========================  ================================================
+        Variable                    Description
+        ==========================  ================================================
+        ``forloop.counter``         The current iteration of the loop (1-indexed)
+        ``forloop.counter0``        The current iteration of the loop (0-indexed)
+        ``forloop.first``           True if this is the first time through the loop
+        ``forloop.last``            True if this is the last time through the loop
+        ``forloop.parentloop``      For nested loops, this is the loop "above" the
+                                    current one
+        ==========================  ================================================
+    
+``if``
+    The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
+    exists, is not empty, and is not a false boolean value) the contents of the
+    block are output::
+    
+        {% if athlete_list %}
+            Number of athletes: {{ athlete_list|count }}
+        {% else %}
+            No athletes.
         {% endif %}
-    {% endif %}
-
-ifchanged
-`````````
-
-Check if a value has changed from the last iteration of a loop.
-
-The 'ifchanged' block tag is used within a loop. It checks its own rendered
-contents against its previous state and only displays its content if the value
-has changed::
-
-    <h1>Archive for {{ year }}</h1>
-
-    {% for date in days %}
-    {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
-    <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
-    {% endfor %}
-
-ifnotequal
-``````````
-
-Output the contents of the block if the two arguments do not equal each other.
-
-Example::
-
-    {% ifnotequal user.id_ comment.user_id %}
-        ...
-    {% endifnotequal %}
-
-load
-````
-
-Load a custom template tag set.
-
-See `Custom tag and filter libraries`_ for more information.
-
-now
-```
-
-Display the date, formatted according to the given string.
-
-Uses the same format as PHP's ``date()`` function; see http://php.net/date
-for all the possible values.
-
-Sample usage::
-
-    It is {% now "jS F Y H:i" %}
-
-regroup
-```````
-
-Regroup a list of alike objects by a common attribute.
-
-This complex tag is best illustrated by use of an example:  say that ``people``
-is a list of ``Person`` objects that have ``first_name``, ``last_name``, and
-``gender`` attributes, and you'd like to display a list that looks like:
-
-    * Male:
-        * George Bush
-        * Bill Clinton
-    * Female:
-        * Margaret Thatcher
-        * Colendeeza Rice
-    * Unknown:
-        * Janet Reno
-
-The following snippet of template code would accomplish this dubious task::
-
-    {% regroup people by gender as grouped %}
-    <ul>
-    {% for group in grouped %}
-        <li>{{ group.grouper }}
+    
+    In the above, if ``athlete_list`` is not empty, the number of athletes will be
+    displayed by the ``{{ athlete_list|count }}`` variable.
+    
+    As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
+    will be displayed if the test fails.
+    
+    ``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
+    a given variable::
+    
+        {% if not athlete_list %}
+            There are no athletes.
+        {% endif %}
+        
+        {% if athlete_list or coach_list %}
+            There are some athletes or some coaches.
+        {% endif %}
+        
+        {% if not athlete_list or coach_list %}
+            There are no athletes or there are some coaches (OK, so 
+            writing English translations of boolean logic sounds 
+            stupid; it's not my fault).
+        {% endif %}
+    
+    For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if`` 
+    tags instead::
+    
+        {% if athlete_list %}
+            {% if coach_list %}
+                Number of athletes: {{ athlete_list|count }}.
+                Number of coaches: {{ coach_list|count }}.
+            {% endif %}
+        {% endif %}
+    
+``ifchanged``
+    Check if a value has changed from the last iteration of a loop.
+    
+    The 'ifchanged' block tag is used within a loop. It checks its own rendered
+    contents against its previous state and only displays its content if the value
+    has changed::
+    
+        <h1>Archive for {{ year }}</h1>
+    
+        {% for date in days %}
+        {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
+        <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
+        {% endfor %}
+    
+``ifnotequal``
+    Output the contents of the block if the two arguments do not equal each other.
+    
+    Example::
+    
+        {% ifnotequal user.id_ comment.user_id %}
+            ...
+        {% endifnotequal %}
+    
+``load``
+    Load a custom template tag set.
+    
+    See `Custom tag and filter libraries`_ for more information.
+    
+``now``
+    Display the date, formatted according to the given string.
+    
+    Uses the same format as PHP's ``date()`` function; see http://php.net/date
+    for all the possible values.
+    
+    Sample usage::
+    
+        It is {% now "jS F Y H:i" %}
+    
+``regroup``
+    Regroup a list of alike objects by a common attribute.
+    
+    This complex tag is best illustrated by use of an example:  say that ``people``
+    is a list of ``Person`` objects that have ``first_name``, ``last_name``, and
+    ``gender`` attributes, and you'd like to display a list that looks like:
+    
+        * Male:
+            * George Bush
+            * Bill Clinton
+        * Female:
+            * Margaret Thatcher
+            * Colendeeza Rice
+        * Unknown:
+            * Janet Reno
+    
+    The following snippet of template code would accomplish this dubious task::
+    
+        {% regroup people by gender as grouped %}
         <ul>
-            {% for item in group.list %}
-            <li>{{ item }}</li>
-            {% endfor %}
+        {% for group in grouped %}
+            <li>{{ group.grouper }}
+            <ul>
+                {% for item in group.list %}
+                <li>{{ item }}</li>
+                {% endfor %}
+            </ul>
+        {% endfor %}
         </ul>
-    {% endfor %}
-    </ul>
-
-As you can see, ``{% regroup %}`` populates a variable with a list of objects
-with ``grouper`` and ``list`` attributes.  ``grouper`` contains the item that
-was grouped by; ``list`` contains the list of objects that share that
-``grouper``.  In this case, ``grouper`` would be ``Male``, ``Female`` and
-``Unknown``, and ``list`` is the list of people with those genders.
-
-Note that ``{% regroup %}`` does not work when the list to be grouped is not
-sorted by the key you are grouping by!  This means that if your list of people
-was not sorted by gender, you'd need to make sure it is sorted before using it,
-i.e.::
-
-    {% regroup people|dictsort:"gender" by gender as grouped %}
-
-ssi
-```
-
-Output the contents of a given file into the page.
-
-Like a simple "include" tag, the ``ssi`` tag includes the contents
-of another file -- which must be specified using an absolute page --
-in the current page::
-
-    {% ssi /home/html/ljworld.com/includes/right_generic.html %}
-
-If the optional "parsed" parameter is given, the contents of the included
-file are evaluated as template code, with the current context::
-
-    {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
-
-templatetag
-```````````
-
-Output one of the bits used to compose template tags.
-
-Since the template system has no concept of "escaping", to display one of the
-bits used in template tags, you must use the ``{% templatetag %}`` tag.
-
-The argument tells which template bit to output:
-
-    ==================  =======
-    Argument            Outputs
-    ==================  =======
-    ``openblock``       ``{%``
-    ``closeblock``      ``%}``
-    ``openvariable``    ``{{``
-    ``closevariable``   ``}}``
-    ==================  =======
-
-widthratio
-``````````
-
-For creating bar charts and such, this tag calculates the ratio of a given value
-to a maximum value, and then applies that ratio to a constant.
-
-For example::
-
-    <img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' />
-
-Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
-above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
-which is rounded up to 88).
+    
+    As you can see, ``{% regroup %}`` populates a variable with a list of objects
+    with ``grouper`` and ``list`` attributes.  ``grouper`` contains the item that
+    was grouped by; ``list`` contains the list of objects that share that
+    ``grouper``.  In this case, ``grouper`` would be ``Male``, ``Female`` and
+    ``Unknown``, and ``list`` is the list of people with those genders.
+    
+    Note that ``{% regroup %}`` does not work when the list to be grouped is not
+    sorted by the key you are grouping by!  This means that if your list of people
+    was not sorted by gender, you'd need to make sure it is sorted before using it,
+    i.e.::
+    
+        {% regroup people|dictsort:"gender" by gender as grouped %}
+    
+``ssi``
+    Output the contents of a given file into the page.
+    
+    Like a simple "include" tag, the ``ssi`` tag includes the contents
+    of another file -- which must be specified using an absolute page --
+    in the current page::
+    
+        {% ssi /home/html/ljworld.com/includes/right_generic.html %}
+    
+    If the optional "parsed" parameter is given, the contents of the included
+    file are evaluated as template code, with the current context::
+    
+        {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
+    
+``templatetag``
+    Output one of the bits used to compose template tags.
+    
+    Since the template system has no concept of "escaping", to display one of the
+    bits used in template tags, you must use the ``{% templatetag %}`` tag.
+    
+    The argument tells which template bit to output:
+    
+        ==================  =======
+        Argument            Outputs
+        ==================  =======
+        ``openblock``       ``{%``
+        ``closeblock``      ``%}``
+        ``openvariable``    ``{{``
+        ``closevariable``   ``}}``
+        ==================  =======
+    
+``widthratio``
+    For creating bar charts and such, this tag calculates the ratio of a given value
+    to a maximum value, and then applies that ratio to a constant.
+    
+    For example::
+    
+        <img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' />
+    
+    Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
+    above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
+    which is rounded up to 88).
 
 Built-in filter reference
 -------------------------
 
-add
-```
-Adds the arg to the value
-
-addslashes
-``````````
-Adds slashes - useful for passing strings to JavaScript, for example.
-
-capfirst
-````````
-Capitalizes the first character of the value
-
-center
-``````
-Centers the value in a field of a given width
-
-cut
-```
-Removes all values of arg from the given string
-
-date
-````
-Formats a date according to the given format (same as the now_ tag)
-
-default
-```````
-If value is unavailable, use given default
-
-dictsort
-````````
-Takes a list of dicts, returns that list sorted by the property given in the
-argument.
-
-dictsortreversed
-````````````````
-Takes a list of dicts, returns that list sorted in reverse order by the property
-given in the argument.
-
-divisibleby
-```````````
-Returns true if the value is divisible by the argument
-
-escape
-``````
-Escapes a string's HTML
-
-filesizeformat
-``````````````
-Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
-bytes, etc).
-
-first
-`````
-Returns the first item in a list
-
-fix_ampersands
-``````````````
-Replaces ampersands with ``&amp;`` entities
-
-floatformat
-```````````
-Displays a floating point number as 34.2 (with one decimal places) - but
-only if there's a point to be displayed
-
-get_digit
-`````````
-Given a whole number, returns the requested digit of it, where 1 is the
-right-most digit, 2 is the second-right-most digit, etc. Returns the
-original value for invalid input (if input or argument is not an integer,
-or if argument is less than 1). Otherwise, output is always an integer.
-
-join
-````
-Joins a list with a string, like Python's ``str.join(list)``
-
-length
-``````
-Returns the length of the value - useful for lists
-
-length_is
-`````````
-Returns a boolean of whether the value's length is the argument
-
-linebreaks
-``````````
-Converts newlines into <p> and <br />s
-
-linebreaksbr
-````````````
-Converts newlines into <br />s
-
-linenumbers
-```````````
-Displays text with line numbers
-
-ljust
-`````
-Left-aligns the value in a field of a given width
-
-Argument: field size
-
-lower
-`````
-Converts a string into all lowercase
-
-make_list
-`````````
-Returns the value turned into a list. For an integer, it's a list of
-digits. For a string, it's a list of characters.
-
-phone2numeric
-`````````````
-Takes a phone number and converts it in to its numerical equivalent
-
-pluralize
-`````````
-Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'
-
-pprint
-``````
-A wrapper around pprint.pprint -- for debugging, really
-
-random
-``````
-Returns a random item from the list
-
-removetags
-```````````
-Removes a space separated list of [X]HTML tags from the output
-
-rjust
-`````
-Right-aligns the value in a field of a given width
-
-Argument: field size
-
-slice
-`````
-Returns a slice of the list.
-
-Uses the same syntax as Python's list slicing; see
-http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
-for an introduction.
-
-slugify
-```````
-Converts to lowercase, removes non-alpha chars and converts spaces to hyphens
-
-stringformat
-````````````
-Formats the variable according to the argument, a string formatting specifier.
-This specifier uses Python string formating syntax, with the exception that
-the leading "%" is dropped.
-
-See http://docs.python.org/lib/typesseq-strings.html for documentation
-of Python string formatting
-
-striptags
-`````````
-Strips all [X]HTML tags
-
-time
-````
-Formats a time according to the given format (same as the now_ tag).
-
-timesince
-`````````
-Formats a date as the time since that date (i.e. "4 days, 6 hours")
-
-title
-`````
-Converts a string into titlecase
-
-truncatewords
-`````````````
-Truncates a string after a certain number of words
-
-Argument: Number of words to truncate after
-
-unordered_list
-``````````````
-Recursively takes a self-nested list and returns an HTML unordered list --
-WITHOUT opening and closing <ul> tags.
-
-The list is assumed to be in the proper format. For example, if ``var`` contains
-``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
-then ``{{ var|unordered_list }}`` would return::
-
-    <li>States
-    <ul>
-            <li>Kansas
-            <ul>
-                    <li>Lawrence</li>
-                    <li>Topeka</li>
-            </ul>
-            </li>
-            <li>Illinois</li>
-    </ul>
-    </li>
-
-upper
-`````
-Converts a string into all uppercase
-
-urlencode
-`````````
-Escapes a value for use in a URL
-
-urlize
-``````
-Converts URLs in plain text into clickable links
-
-urlizetrunc
-```````````
-Converts URLs into clickable links, truncating URLs to the given character limit
-
-Argument: Length to truncate URLs to.
-
-wordcount
-`````````
-Returns the number of words
-
-wordwrap
-````````
-Wraps words at specified line length
-
-Argument: number of words to wrap the text at.
-
-yesno
-`````
-Given a string mapping values for true, false and (optionally) None,
-returns one of those strings according to the value:
-
-==========  ======================  ==================================
-Value       Argument                Outputs
-==========  ======================  ==================================
-``True``    ``"yeah,no,maybe"``     ``yeah``
-``False``   ``"yeah,no,maybe"``     ``no``
-``None``    ``"yeah,no,maybe"``     ``maybe``
-``None``    ``"yeah,no"``           ``"no"`` (converts None to False
-                                    if no mapping for None is given.
-==========  ======================  ==================================
+``add``
+    Adds the arg to the value
+    
+``addslashes``
+    Adds slashes - useful for passing strings to JavaScript, for example.
+    
+``capfirst``
+    Capitalizes the first character of the value
+    
+``center``
+    Centers the value in a field of a given width
+    
+``cut``
+    Removes all values of arg from the given string
+    
+``date``
+    Formats a date according to the given format (same as the now_ tag)
+    
+``default``
+    If value is unavailable, use given default
+    
+``dictsort``
+    Takes a list of dicts, returns that list sorted by the property given in the
+    argument.
+    
+``dictsortreversed``
+    Takes a list of dicts, returns that list sorted in reverse order by the property
+    given in the argument.
+    
+``divisibleby``
+    Returns true if the value is divisible by the argument
+    
+``escape``
+    Escapes a string's HTML
+    
+``filesizeformat``
+    Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
+    bytes, etc).
+    
+``first``
+    Returns the first item in a list
+    
+``fix_ampersands``
+    Replaces ampersands with ``&amp;`` entities
+    
+``floatformat``
+    Displays a floating point number as 34.2 (with one decimal places) - but
+    only if there's a point to be displayed
+    
+``get_digit``
+    Given a whole number, returns the requested digit of it, where 1 is the
+    right-most digit, 2 is the second-right-most digit, etc. Returns the
+    original value for invalid input (if input or argument is not an integer,
+    or if argument is less than 1). Otherwise, output is always an integer.
+    
+``join``
+    Joins a list with a string, like Python's ``str.join(list)``
+    
+``length``
+    Returns the length of the value - useful for lists
+    
+``length_is``
+    Returns a boolean of whether the value's length is the argument
+    
+``linebreaks``
+    Converts newlines into <p> and <br />s
+    
+``linebreaksbr``
+    Converts newlines into <br />s
+    
+``linenumbers``
+    Displays text with line numbers
+    
+``ljust``
+    Left-aligns the value in a field of a given width
+    
+    Argument: field size
+    
+``lower``
+    Converts a string into all lowercase
+    
+``make_list``
+    Returns the value turned into a list. For an integer, it's a list of
+    digits. For a string, it's a list of characters.
+    
+``phone2numeric``
+    Takes a phone number and converts it in to its numerical equivalent
+    
+``pluralize``
+    Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'
+    
+``pprint``
+    A wrapper around pprint.pprint -- for debugging, really
+    
+``random``
+    Returns a random item from the list
+    
+``removetags``
+    Removes a space separated list of [X]HTML tags from the output
+    
+``rjust``
+    Right-aligns the value in a field of a given width
+    
+    Argument: field size
+    
+``slice``
+    Returns a slice of the list.
+    
+    Uses the same syntax as Python's list slicing; see
+    http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
+    for an introduction.
+    
+``slugify``
+    Converts to lowercase, removes non-alpha chars and converts spaces to hyphens
+    
+``stringformat``
+    Formats the variable according to the argument, a string formatting specifier.
+    This specifier uses Python string formating syntax, with the exception that
+    the leading "%" is dropped.
+    
+    See http://docs.python.org/lib/typesseq-strings.html for documentation
+    of Python string formatting
+    
+``striptags``
+    Strips all [X]HTML tags
+    
+``time``
+    Formats a time according to the given format (same as the now_ tag).
+    
+``timesince``
+    Formats a date as the time since that date (i.e. "4 days, 6 hours")
+    
+``title``
+    Converts a string into titlecase
+    
+``truncatewords``
+    Truncates a string after a certain number of words
+    
+    Argument: Number of words to truncate after
+    
+``unordered_list``
+    Recursively takes a self-nested list and returns an HTML unordered list --
+    WITHOUT opening and closing <ul> tags.
+    
+    The list is assumed to be in the proper format. For example, if ``var`` contains
+    ``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
+    then ``{{ var|unordered_list }}`` would return::
+    
+        <li>States
+        <ul>
+                <li>Kansas
+                <ul>
+                        <li>Lawrence</li>
+                        <li>Topeka</li>
+                </ul>
+                </li>
+                <li>Illinois</li>
+        </ul>
+        </li>
+    
+``upper``
+    Converts a string into all uppercase
+    
+``urlencode``
+    Escapes a value for use in a URL
+    
+``urlize``
+    Converts URLs in plain text into clickable links
+    
+``urlizetrunc``
+    Converts URLs into clickable links, truncating URLs to the given character limit
+    
+    Argument: Length to truncate URLs to.
+    
+``wordcount``
+    Returns the number of words
+    
+``wordwrap``
+    Wraps words at specified line length
+    
+    Argument: number of words to wrap the text at.
+    
+``yesno``
+    Given a string mapping values for true, false and (optionally) None,
+    returns one of those strings according to the value:
+    
+    ==========  ======================  ==================================
+    Value       Argument                Outputs
+    ==========  ======================  ==================================
+    ``True``    ``"yeah,no,maybe"``     ``yeah``
+    ``False``   ``"yeah,no,maybe"``     ``no``
+    ``None``    ``"yeah,no,maybe"``     ``maybe``
+    ``None``    ``"yeah,no"``           ``"no"`` (converts None to False
+                                        if no mapping for None is given.
+    ==========  ======================  ==================================