gis: Merged revisions 5491-5539 via svnmerge from

     http://code.djangoproject.com/svn/django/trunk


git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@5540 bcc190cf-cafb-0310-a4f2-bffc1f526a37

10 files changed, 61 insertions, 81 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index 972ca42073..5e5ecdf908 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -325,7 +325,7 @@ Manually checking a user's password
 
 If you'd like to manually authenticate a user by comparing a
 plain-text password to the hashed password in the database, use the
-convenience function `django.contrib.auth.models.check_password`. It
+convenience function ``django.contrib.auth.models.check_password``. It
 takes two arguments: the plain-text password to check, and the full
 value of a user's ``password`` field in the database to check against,
 and returns ``True`` if they match, ``False`` otherwise.
diff --git a/docs/faq.txt b/docs/faq.txt
index bdd8c5360e..67ed8a49a5 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -104,7 +104,7 @@ Lawrence, Kansas, USA.
 
 `Wilson Miner`_
     Wilson's design-fu makes us all look like rock stars. By day, he's an
-    interactive designer for `Apple`. Don't ask him what he's working on, or
+    interactive designer for `Apple`_. Don't ask him what he's working on, or
     he'll have to kill you. He lives in San Francisco.
 
     On IRC, Wilson goes by ``wilsonian``.
@@ -301,7 +301,7 @@ means it can run on a variety of server platforms.
 
 If you want to use Django with a database, which is probably the case, you'll
 also need a database engine. PostgreSQL_ is recommended, because we're
-PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported.
+PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported.
 
 .. _Python: http://www.python.org/
 .. _Apache 2: http://httpd.apache.org/
@@ -310,6 +310,7 @@ PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported.
 .. _PostgreSQL: http://www.postgresql.org/
 .. _MySQL: http://www.mysql.com/
 .. _`SQLite 3`: http://www.sqlite.org/
+.. _Oracle: http://www.oracle.com/
 
 Do I lose anything by using Python 2.3 versus newer Python versions, such as Python 2.5?
 ----------------------------------------------------------------------------------------
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 359a82506a..2b80348903 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -754,10 +754,10 @@ If the results are paginated, the context will contain these extra variables:
 
     * ``previous``: The previous page number, as an integer. This is 1-based.
 
-    * `last_on_page`: The number of the
+    * ``last_on_page``: The number of the
       last result on the current page. This is 1-based.
 
-    * `first_on_page`: The number of the
+    * ``first_on_page``: The number of the
       first result on the current page. This is 1-based.
 
     * ``pages``: The total number of pages, as an integer.
diff --git a/docs/install.txt b/docs/install.txt
index 4f5a4bbe31..99aad4e52d 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -17,8 +17,10 @@ probably already have it installed.
 Install Apache and mod_python
 =============================
 
-If you just want to experiment with Django, skip this step. Django comes with
-its own Web server for development purposes.
+If you just want to experiment with Django, skip ahead to the next
+section; Django includes a lightweight web server you can use for
+testing, so you won't need to set up Apache until you're ready to
+deploy Django in production.
 
 If you want to use Django on a production site, use Apache with `mod_python`_.
 mod_python is similar to mod_perl -- it embeds Python within Apache and loads
@@ -62,6 +64,8 @@ installed.
 
 * If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher.
 
+* If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher.
+
 .. _PostgreSQL: http://www.postgresql.org/
 .. _MySQL: http://www.mysql.com/
 .. _Django's ticket system: http://code.djangoproject.com/report/1
@@ -71,6 +75,7 @@ installed.
 .. _SQLite: http://www.sqlite.org/
 .. _pysqlite: http://initd.org/tracker/pysqlite
 .. _MySQL backend: ../databases/
+.. _cx_Oracle: http://www.python.net/crew/atuining/cx_Oracle/
 
 Remove any old versions of Django
 =================================
@@ -83,23 +88,20 @@ If you installed Django using ``setup.py install``, uninstalling
 is as simple as deleting the ``django`` directory from your Python
 ``site-packages``.
 
-If you installed Django from a Python Egg, remove the Django ``.egg`` file,
+If you installed Django from a Python egg, remove the Django ``.egg`` file,
 and remove the reference to the egg in the file named ``easy-install.pth``.
 This file should also be located in your ``site-packages`` directory.
 
 .. admonition:: Where are my ``site-packages`` stored?
 
     The location of the ``site-packages`` directory depends on the operating
-    system, and the location in which Python was installed. However, the
-    following locations are common:
-
-    * If you're using Linux: ``/usr/lib/python2.X/site-packages``
+    system, and the location in which Python was installed. To find out your
+    system's ``site-packages`` location, execute the following::
 
-    * If you're using Windows: ``C:\Python2.X\lib\site-packages``
+        python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
 
-    * If you're using MacOSX: ``/Library/Python2.X/site-packages`` or
-      ``/Library/Frameworks/Python.framework/Versions/2.X/lib/python2.X/site-packages/``
-      (in later releases).
+    (Note that this should be run from a shell prompt, not a Python interactive
+    prompt.)
 
 Install the Django code
 =======================
@@ -138,12 +140,15 @@ latest bug fixes and improvements, follow these instructions:
 
 1. Make sure you have Subversion_ installed.
 2. Check out the Django code into your Python ``site-packages`` directory.
+
    On Linux / Mac OSX / Unix, do this::
 
        svn co http://code.djangoproject.com/svn/django/trunk/ django_src
-       ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django
+       ln -s `pwd`/django_src/django SITE-PACKAGES-DIR/django
 
-   (In the above line, change ``python2.3`` to match your current Python version.)
+   (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
+   your system's ``site-packages`` directory, as explained in the
+   "Where are my ``site-packages`` stored?" section above.)
 
    On Windows, do this::
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 09440f2b56..f7b56110d6 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -492,6 +492,11 @@ has ``null=True``, that means it has two possible values for "no data":
 possible values for "no data;" Django convention is to use the empty
 string, not ``NULL``.
 
+.. note::
+    Due to database limitations, when using the Oracle backend the
+    ``null=True`` option will be coerced for string-based fields that can
+    blank, and the value ``NULL`` will be stored to denote the empty string.
+
 ``blank``
 ~~~~~~~~~
 
@@ -586,6 +591,13 @@ scenes.
 If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
 statement for this field.
 
+``db_tablespace``
+~~~~~~~~~~~~~~~~~
+
+If this field is indexed, the name of the database tablespace to use for the
+index. The default is the ``db_tablespace`` of the model, if any. If the
+backend doesn't support tablespaces, this option is ignored.
+
 ``default``
 ~~~~~~~~~~~
 
@@ -996,6 +1008,12 @@ If your database table name is an SQL reserved word, or contains characters
 that aren't allowed in Python variable names -- notably, the hyphen --
 that's OK. Django quotes column and table names behind the scenes.
 
+``db_tablespace``
+-----------------
+
+The name of the database tablespace to use for the model. If the backend
+doesn't support tablespaces, this option is ignored.
+
 ``get_latest_by``
 -----------------
 
@@ -1876,11 +1894,11 @@ used by the SQLite Python bindings. This is for the sake of consistency and
 sanity.)
 
 A final note: If all you want to do is a custom ``WHERE`` clause, you can just
-just the ``where``, ``tables`` and ``params`` arguments to the standard lookup
+use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
 API. See `Other lookup options`_.
 
 .. _Python DB-API: http://www.python.org/peps/pep-0249.html
-.. _Other lookup options: ../db-api/#extra-params-select-where-tables
+.. _Other lookup options: ../db-api/#extra-select-none-where-none-params-none-tables-none
 .. _transaction handling: ../transactions/
 
 Overriding default model methods
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 1511791a7d..41db04a7dd 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -110,7 +110,7 @@ shortly.
 Creating ``Form`` instances
 ---------------------------
 
-A ``Form`` instance is either **bound** or **unbound** to a set of data.
+A ``Form`` instance is either **bound** to a set of data, or **unbound**.
 
     * If it's **bound** to a set of data, it's capable of validating that data
       and rendering the form as HTML with the data displayed in the HTML.
diff --git a/docs/settings.txt b/docs/settings.txt
index 12e6dab4bc..897cdc8099 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -244,9 +244,9 @@ DATABASE_ENGINE
 
 Default: ``''`` (Empty string)
 
-Which database backend to use. Either ``'postgresql_psycopg2'``, 
-``'postgresql'``, ``'mysql'``,  ``'mysql_old'``, ``'sqlite3'`` or
-``'ado_mssql'``.
+The database backend to use. Either ``'postgresql_psycopg2'``,
+``'postgresql'``, ``'mysql'``,  ``'mysql_old'``, ``'sqlite3'``,
+``'oracle'``, or ``'ado_mssql'``.
 
 DATABASE_HOST
 -------------
diff --git a/docs/templates.txt b/docs/templates.txt
index cb8e238f43..c32b1af1dd 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -1266,7 +1266,8 @@ Converts URLs in plain text into clickable links.
 urlizetrunc
 ~~~~~~~~~~~
 
-Converts URLs into clickable links, truncating URLs to the given character limit.
+Converts URLs into clickable links, truncating URLs longer than the given
+character limit.
 
 **Argument:** Length to truncate URLs to
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index c967df1a49..7171f32612 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -219,13 +219,13 @@ be replaced with the name of the invalid variable.
 
     While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool,
     it is a bad idea to turn it on as a 'development default'.
-
+    
     Many templates, including those in the Admin site, rely upon the
     silence of the template system when a non-existent variable is
     encountered. If you assign a value other than ``''`` to
     ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering
     problems with these templates and sites.
-
+    
     Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled
     in order to debug a specific template problem, then cleared
     once debugging is complete.
@@ -342,7 +342,7 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
 
     * ``user`` -- An ``auth.User`` instance representing the currently
       logged-in user (or an ``AnonymousUser`` instance, if the client isn't
-      logged in). See the `user authentication docs`.
+      logged in). See the `user authentication docs`_.
 
     * ``messages`` -- A list of messages (as strings) for the currently
       logged-in user. Behind the scenes, this calls
@@ -693,15 +693,14 @@ how the compilation works and how the rendering works.
 
 When Django compiles a template, it splits the raw template text into
 ''nodes''. Each node is an instance of ``django.template.Node`` and has
-either a ``render()`` or ``iter_render()`` method. A compiled template is,
-simply, a list of ``Node`` objects. When you call ``render()`` on a compiled
-template object, the template calls ``render()`` on each ``Node`` in its node
-list, with the given context. The results are all concatenated together to
-form the output of the template.
+a ``render()`` method. A compiled template is, simply, a list of ``Node``
+objects. When you call ``render()`` on a compiled template object, the template
+calls ``render()`` on each ``Node`` in its node list, with the given context.
+The results are all concatenated together to form the output of the template.
 
 Thus, to define a custom template tag, you specify how the raw template tag is
 converted into a ``Node`` (the compilation function), and what the node's
-``render()`` or ``iter_render()`` method does.
+``render()`` method does.
 
 Writing the compilation function
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -771,8 +770,7 @@ Writing the renderer
 ~~~~~~~~~~~~~~~~~~~~
 
 The second step in writing custom tags is to define a ``Node`` subclass that
-has a ``render()`` method (we will discuss the ``iter_render()`` alternative
-in `Improving rendering speed`_, below).
+has a ``render()`` method.
 
 Continuing the above example, we need to define ``CurrentTimeNode``::
 
@@ -876,7 +874,7 @@ current context, available in the ``render`` method::
         def __init__(self, date_to_be_formatted, format_string):
             self.date_to_be_formatted = date_to_be_formatted
             self.format_string = format_string
-
+        
         def render(self, context):
             try:
                 actual_date = resolve_variable(self.date_to_be_formatted, context)
@@ -1177,48 +1175,6 @@ For more examples of complex rendering, see the source code for ``{% if %}``,
 
 .. _configuration:
 
-Improving rendering speed
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For most practical purposes, the ``render()`` method on a ``Node`` will be
-sufficient and the simplest way to implement a new tag. However, if your
-template tag is expected to produce large strings via ``render()``, you can
-speed up the rendering process (and reduce memory usage) using iterative
-rendering via the ``iter_render()`` method.
-
-The ``iter_render()`` method should either be an iterator that yields string
-chunks, one at a time, or a method that returns a sequence of string chunks.
-The template renderer will join the successive chunks together when creating
-the final output. The improvement over the ``render()`` method here is that
-you do not need to create one large string containing all the output of the
-``Node``, instead you can produce the output in smaller chunks.
-
-By way of example, here's a trivial ``Node`` subclass that simply returns the
-contents of a file it is given::
-
-    class FileNode(Node):
-        def __init__(self, filename):
-            self.filename = filename
-
-        def iter_render(self):
-            for line in file(self.filename):
-                yield line
-
-For very large files, the full file contents will never be read entirely into
-memory when this tag is used, which is a useful optimisation.
-
-If you define an ``iter_render()`` method on your ``Node`` subclass, you do
-not need to define a ``render()`` method. The reverse is true as well: the
-default ``Node.iter_render()`` method will call your ``render()`` method if
-necessary. A useful side-effect of this is that you can develop a new tag
-using ``render()`` and producing all the output at once, which is easy to
-debug. Then you can rewrite the method as an iterator, rename it to
-``iter_render()`` and everything will still work.
-
-It is compulsory, however, to define *either* ``render()`` or ``iter_render()``
-in your subclass. If you omit them both, a ``TypeError`` will be raised when
-the code is imported.
-
 Configuring the template system in standalone mode
 ==================================================
 
@@ -1250,4 +1206,3 @@ is of obvious interest.
 
 .. _settings file: ../settings/#using-settings-without-the-django-settings-module-environment-variable
 .. _settings documentation: ../settings/
-
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index c40b051b19..d26f654f87 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -10,7 +10,7 @@ poll application.
 It'll consist of two parts:
 
     * A public site that lets people view polls and vote in them.
-    * An admin site that lets you add, change and delete poll.
+    * An admin site that lets you add, change and delete polls.
 
 We'll assume you have `Django installed`_ already. You can tell Django is
 installed by running the Python interactive interpreter and typing