Documentation (and some small source code) edits from [17432] - [17537]

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

5 files changed, 94 insertions, 90 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index c40ce89204..1fde2ce5f5 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -697,8 +697,8 @@ subclass::
 
       .. note::
 
-        The ``FieldListFilter`` API is currently considered internal and prone
-        to refactoring.
+        The ``FieldListFilter`` API is considered internal and might be
+        changed.
 
     .. versionadded:: 1.4
 
diff --git a/docs/ref/contrib/gis/install.txt b/docs/ref/contrib/gis/install.txt
index 9d67242b2d..419ed59369 100644
--- a/docs/ref/contrib/gis/install.txt
+++ b/docs/ref/contrib/gis/install.txt
@@ -44,7 +44,7 @@ Because GeoDjango is included with Django, please refer to Django's
 
 .. _spatial_database:
 
-Spatial Database
+Spatial database
 ----------------
 PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
 the spatial databases currently supported.
@@ -69,7 +69,7 @@ SQLite              GEOS, GDAL, PROJ.4, SpatiaLite  3.6.+               Requires
 
 .. _geospatial_libs:
 
-Geospatial Libraries
+Geospatial libraries
 --------------------
 GeoDjango uses and/or provides interfaces for the following open source
 geospatial libraries:
@@ -104,7 +104,7 @@ __ http://www.gaia-gis.it/spatialite/index.html
 
 .. _build_from_source:
 
-Building from Source
+Building from source
 ====================
 
 When installing from source on UNIX and GNU/Linux systems, please follow
@@ -156,7 +156,7 @@ script, compile, and install::
 Troubleshooting
 ^^^^^^^^^^^^^^^
 
-Can't find GEOS Library
+Can't find GEOS library
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 When GeoDjango can't find GEOS, this error is raised:
@@ -297,7 +297,7 @@ __ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython
 Troubleshooting
 ^^^^^^^^^^^^^^^
 
-Can't find GDAL Library
+Can't find GDAL library
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
@@ -410,7 +410,7 @@ __ http://www.sqlite.org/download.html
 
 .. _spatialitebuild :
 
-SpatiaLite Library (``libspatialite``) and Tools (``spatialite``)
+SpatiaLite library (``libspatialite``) and tools (``spatialite``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 After SQLite has been built with the R*Tree module enabled, get the latest
@@ -495,12 +495,12 @@ to build and install::
 
     $ sudo python setup.py install
 
-Post-Installation
+Post-installation
 =================
 
 .. _spatialdb_template:
 
-Creating a Spatial Database Template for PostGIS
+Creating a spatial database template for PostGIS
 ------------------------------------------------
 
 Creating a spatial database with PostGIS is different than normal because
@@ -549,7 +549,7 @@ These commands may be placed in a shell script for later use; for convenience
 the following scripts are available:
 
 ===============  =============================================
-PostGIS Version  Bash Shell Script
+PostGIS version  Bash shell script
 ===============  =============================================
 1.3              :download:`create_template_postgis-1.3.sh`
 1.4              :download:`create_template_postgis-1.4.sh`
@@ -572,44 +572,34 @@ Afterwards, you may create a spatial database by simply specifying
 
 .. _create_spatialite_db:
 
-Creating a Spatial Database for SpatiaLite
--------------------------------------------
+Creating a spatial database for SpatiaLite
+------------------------------------------
 
-After the SpatiaLite library and tools have been installed, it is now possible
-to create a spatial database for use with GeoDjango.
+After you've installed SpatiaLite, you'll need to create a number of spatial
+metadata tables in your database in order to perform spatial queries.
 
-For this, a number of spatial metadata tables must be created in the database
-before any spatial query is performed against it.
-
-If you are using SpatiaLite 3.0 or newer then use the ``spatialite`` utility to
-call the ``InitSpatiaMetaData()`` function which will take care of that (you can
-safely ignore the error messages shown) then you can skip the rest of this
-section::
+If you're using SpatiaLite 3.0 or newer, use the ``spatialite`` utility to
+call the ``InitSpatiaMetaData()`` function, like this::
 
    $ spatialite geodjango.db "SELECT InitSpatialMetaData();"
    the SPATIAL_REF_SYS table already contains some row(s)
     InitSpatiaMetaData ()error:"table spatial_ref_sys already exists"
    0
 
-If you re using a version of Spatialite older than 3.0 then to achieve the same
-result you need to download a database initialization file and execute the SQL
-queries it contains against your database.
+You can safely ignore the error messages shown. When you've done this, you can
+skip the rest of this section.
+
+If you're using a version of SpatiaLite older than 3.0, you'll need to download
+a database-initialization file and execute its SQL queries in your database.
 
-First, get it from the appropiate SpatiaLite Resources page (i.e.
+First, get it from the appropriate SpatiaLite Resources page (
 http://www.gaia-gis.it/spatialite-2.3.1/resources.html for 2.3 or
 http://www.gaia-gis.it/spatialite-2.4.0/ for 2.4)::
 
    $ wget http://www.gaia-gis.it/spatialite-2.3.1/init_spatialite-2.3.sql.gz
    $ gunzip init_spatialite-2.3.sql.gz
 
-(Or, if you are using SpatiaLite 2.4 then do::
-
-   $ wget http://www.gaia-gis.it/spatialite-2.4.0/init_spatialite-2.4.sql.gz
-   $ gunzip init_spatialite-2.4.sql.gz
-
-)
-
-Now, the ``spatialite`` command can be used to initialize a spatial database::
+Then, use the ``spatialite`` command to initialize a spatial database::
 
    $ spatialite geodjango.db < init_spatialite-2.X.sql
 
@@ -629,15 +619,15 @@ features such as the geographic admin or KML sitemaps will not function properly
 
 .. _addgoogleprojection:
 
-Add Google Projection to ``spatial_ref_sys`` table
+Add Google projection to ``spatial_ref_sys`` table
 --------------------------------------------------
 
 .. versionchanged:: 1.2
 
 .. note::
 
-    If running PostGIS 1.4 and above, the entry is already included in the
-    default ``spatial_ref_sys`` table.  You can skip this step.
+    If you're running PostGIS 1.4 or above, you can skip this step. The entry
+    is already included in the default ``spatial_ref_sys`` table.
 
 In order to conduct database transformations to the so-called "Google"
 projection (a spherical mercator projection used by Google Maps),
@@ -678,7 +668,7 @@ __ http://code.djangoproject.com/simpleticket
 
 .. _libsettings:
 
-Library Environment Settings
+Library environment settings
 ----------------------------
 
 By far, the most common problem when installing GeoDjango is that the
@@ -701,7 +691,7 @@ could place the following in their bash profile::
 
     export LD_LIBRARY_PATH=/usr/local/lib
 
-Setting System Library Path
+Setting system library path
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
@@ -740,7 +730,7 @@ Similarly, on Red Hat and CentOS systems::
 
     $ sudo yum install binutils
 
-Platform Specific Instructions
+Platform-specific instructions
 ==============================
 
 .. _macosx:
@@ -749,7 +739,7 @@ Mac OS X
 --------
 
 Because of the variety of packaging systems available for OS X, users have
-several different options for installing GeoDjango.  These options are:
+several different options for installing GeoDjango. These options are:
 
 * :ref:`kyngchaos`
 * :ref:`fink`
@@ -789,7 +779,7 @@ __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
 
 .. _kyngchaos:
 
-KyngChaos Packages
+KyngChaos packages
 ^^^^^^^^^^^^^^^^^^
 
 William Kyngesburye provides a number of `geospatial library binary packages`__
@@ -952,9 +942,9 @@ Ubuntu & Debian GNU/Linux
 .. note::
 
     The PostGIS SQL files are not placed in the PostgreSQL share directory in
-    the Debian and Ubuntu packages, and are located instead in a special
-    directory depending on the release.  Thus, when :ref:`spatialdb_template`
-    use the :download:`create_template_postgis-debian.sh` script instead.
+    the Debian and Ubuntu packages. Instead, they're located in a special
+    directory depending on the release. In this case, use the
+    :download:`create_template_postgis-debian.sh` script
 
 .. _ubuntu:
 
@@ -1049,10 +1039,11 @@ Debian
 
 4.0 (Etch)
 ^^^^^^^^^^
+
 The situation here is the same as that of Ubuntu :ref:`heron` -- in other words,
 some packages must be built from source to work properly with GeoDjango.
 
-Binary Packages
+Binary packages
 ~~~~~~~~~~~~~~~
 The following command will install acceptable binary packages, as well as
 the development tools necessary to build the rest of the requirements::
@@ -1075,7 +1066,7 @@ Optional packages:
 
 * ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support
 
-Source Packages
+Source packages
 ~~~~~~~~~~~~~~~
 You will still have to install :ref:`geosbuild`, :ref:`proj4`,
 :ref:`postgis`, and :ref:`gdalbuild` from source.  Please follow the
@@ -1104,7 +1095,7 @@ in the above command with the appropriate PostgreSQL version.
 
 .. _post_install:
 
-Post-installation Notes
+Post-installation notes
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 If the PostgreSQL database cluster was not initiated after installing, then it
@@ -1234,7 +1225,7 @@ installer.
 
 .. _OSGeo4W installer: http://trac.osgeo.org/osgeo4w/
 
-Modify Windows Environment
+Modify Windows environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In order to use GeoDjango, you will need to add your Python and OSGeo4W
@@ -1269,8 +1260,8 @@ script, :download:`geodjango_setup.bat`.
     then you will need to modify the ``OSGEO4W_ROOT`` and/or ``PYTHON_ROOT``
     variables accordingly.
 
-Install Django and Setup Database
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Install Django and set up database
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Finally, :ref:`install Django <installing-official-release>` on your system.
 You do not need to create a spatial database template, as one named
diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt
index 9270c9f7d6..a9c86f3c3c 100644
--- a/docs/ref/contrib/gis/testing.txt
+++ b/docs/ref/contrib/gis/testing.txt
@@ -1,11 +1,11 @@
 ======================
-Testing GeoDjango Apps
+Testing GeoDjango apps
 ======================
 
 .. versionchanged:: 1.2
 
 In Django 1.2, the addition of :ref:`spatial-backends` simplified the
-process of testing GeoDjango applications -- the process is now the
+process of testing GeoDjango applications. The process is now the
 same as :doc:`/topics/testing`.
 
 Included in this documentation are some additional notes and settings
@@ -31,7 +31,7 @@ Settings
 .. versionchanged:: 1.2
 
 This setting may be used to customize the name of the PostGIS template
-database to use.  In Django versions 1.2 and above, it automatically
+database to use. In Django versions 1.2 and above, it automatically
 defaults to ``'template_postgis'`` (the same name used in the
 :ref:`installation documentation <spatialdb_template>`).
 
@@ -42,25 +42,25 @@ defaults to ``'template_postgis'`` (the same name used in the
 
 When GeoDjango's spatial backend initializes on PostGIS, it has to perform
 a SQL query to determine the version in order to figure out what
-features are available.  Advanced users wishing to prevent this additional
+features are available. Advanced users wishing to prevent this additional
 query may set the version manually using a 3-tuple of integers specifying
-the major, minor, and subminor version numbers for PostGIS.  For example,
+the major, minor, and subminor version numbers for PostGIS. For example,
 to configure for PostGIS 1.5.2 you would use::
 
     POSTGIS_VERSION = (1, 5, 2)
 
-Obtaining Sufficient Privileges
+Obtaining sufficient privileges
 -------------------------------
 
 Depending on your configuration, this section describes several methods to
 configure a database user with sufficient privileges to run tests for
-GeoDjango applications on PostgreSQL.  If your
+GeoDjango applications on PostgreSQL. If your
 :ref:`spatial database template <spatialdb_template>`
 was created like in the instructions, then your testing database user
-only needs to have the ability to create databases.  In other configurations,
+only needs to have the ability to create databases. In other configurations,
 you may be required to use a database superuser.
 
-Create Database User
+Create database user
 ^^^^^^^^^^^^^^^^^^^^
 
 To make database user with the ability to create databases, use the
@@ -76,7 +76,7 @@ Alternatively, you may alter an existing user's role from the SQL shell
 
     postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
 
-Create Database Superuser
+Create database superuser
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This may be done at the time the user is created, for example::
@@ -89,7 +89,7 @@ is done from an existing superuser account)::
     postgres# ALTER ROLE <user_name> SUPERUSER;
 
 
-Create Local PostgreSQL Database
+Create local PostgreSQL database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 1. Initialize database: ``initdb -D /path/to/user/db``
@@ -114,8 +114,8 @@ spatial database entitled ``template_postgis``.
 SpatiaLite
 ==========
 
-You need to make sure needed spatial tables are created in your test spatial
-database as described in :ref:`create_spatialite_db`. Then all you have to do is::
+Make sure the necessary spatial tables are created in your test spatial
+database, as described in :ref:`create_spatialite_db`. Then just do this::
 
     $ python manage.py test
 
@@ -127,18 +127,18 @@ Settings
 ``SPATIALITE_SQL``
 ^^^^^^^^^^^^^^^^^^
 
-(only relevant when using a SpatiaLite version older than 3.0).
+Only relevant when using a SpatiaLite version older than 3.0.
 
 By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
 same directory where it was invoked (by default the same directory where
-``manage.py`` is located).  If you want to use a different location, then
-you may add the following to your settings::
+``manage.py`` is located). To use a different location, add the following to
+your settings::
 
     SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql'
 
 .. _geodjango-tests:
 
-GeoDjango Tests
+GeoDjango tests
 ===============
 
 .. versionchanged:: 1.3
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 4c83bf0ad0..5c423a55bc 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -954,10 +954,10 @@ creating the ``myapp`` app::
 
 .. versionadded:: 1.4
 
-When Django copies the app template files, it also renders the files
-whose extension matches those passed with the ``--extension`` option (``py``
-by default) and those files which names are passed with the ``--name`` option
-using the template engine. The :class:`template context
+When Django copies the app template files, it also renders certain files
+through the template engine: the files whose extensions match the
+``--extension`` option (``py`` by default) and the files whose names are passed
+with the ``--name`` option. The :class:`template context
 <django.template.Context>` used is:
 
 - Any option passed to the startapp command
@@ -1017,10 +1017,10 @@ when creating the ``myproject`` project::
 
     django-admin.py startproject --template=/Users/jezdez/Code/my_project_template myproject
 
-When Django copies the project template files, it will also render the files
-whose extension matches those passed with the ``--extension`` option (``py``
-by default) and those files which names are passed with the ``--name`` option
-using the template engine. The :class:`template context
+When Django copies the project template files, it also renders certain files
+through the template engine: the files whose extensions match the
+``--extension`` option (``py`` by default) and the files whose names are passed
+with the ``--name`` option. The :class:`template context
 <django.template.Context>` used is:
 
 - Any option passed to the startproject command
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index c394c34045..2b9989b800 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -756,31 +756,44 @@ Default: ``False``
 
 A boolean that turns on/off debug mode.
 
-If you define custom settings, `django/views/debug.py`_ has a
-``HIDDEN_SETTINGS`` regular expression which will hide from the DEBUG view
-anything that contains ``'API'``, ``'TOKEN'``, ``'KEY'``, ``'SECRET'``,
-``'PASS'``, ``'PROFANITIES_LIST'``, or ``'SIGNATURE'``. This allows untrusted
-users to be able to give backtraces without seeing sensitive (or offensive)
-settings.
+Never deploy a site into production with :setting:`DEBUG` turned on.
+
+Did you catch that? NEVER deploy a site into production with :setting:`DEBUG`
+turned on.
+
+One of the main features of debug mode is the display of detailed error pages.
+If your app raises an exception when ``DEBUG`` is ``True``, Django will display
+a detailed traceback, including a lot of metadata about your environment, such
+as all the currently defined Django settings (from ``settings.py``).
+
+As a security measure, Django will *not* include settings that might be
+sensitive (or offensive), such as ``SECRET_KEY`` or ``PROFANITIES_LIST``.
+Specifically, it will exclude any setting whose name includes any of the
+following:
+
+    * API
+    * KEY
+    * PASS
+    * PROFANITIES_LIST
+    * SECRET
+    * SIGNATURE
+    * TOKEN
 
 .. versionchanged:: 1.4
 
-    ``'PASSWORD'`` changed to ``'PASS'``. ``'API'``, ``'TOKEN'``, ``'KEY'`` 
+    We changed ``'PASSWORD'`` ``'PASS'``. ``'API'``, ``'TOKEN'`` and ``'KEY'``
     were added.
 
-Note that due to how regular expression matching works ``'PASS'`` will also
-match PASSWORD, just as ``'TOKEN'`` will also match TOKENIZED and so on.
+Note that these are *partial* matches. ``'PASS'`` will also match PASSWORD,
+just as ``'TOKEN'`` will also match TOKENIZED and so on.
 
 Still, note that there are always going to be sections of your debug output
 that are inappropriate for public consumption. File paths, configuration
-options, and the like all give attackers extra information about your server.
+options and the like all give attackers extra information about your server.
 
 It is also important to remember that when running with :setting:`DEBUG`
 turned on, Django will remember every SQL query it executes. This is useful
-when you are debugging, but on a production server, it will rapidly consume
-memory.
-
-Never deploy a site into production with :setting:`DEBUG` turned on.
+when you're debugging, but it'll rapidly consume memory on a production server.
 
 .. _django/views/debug.py: http://code.djangoproject.com/browser/django/trunk/django/views/debug.py