Edited docs/databases.txt Oracle changes from [6432]

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

docs/databases.txt

@@ -172,22 +172,32 @@ storage engine, you have a couple of options.
 .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
 
 
-Oracle Notes
+Oracle notes
 ============
 
-Django supports `Oracle Database Server`_ versions 9i and higher.  Oracle
+Django supports `Oracle Database Server`_ versions 9i and higher. Oracle
 version 10g or later is required to use Django's ``regex`` and ``iregex`` query
-operators.  You will also need the `cx_Oracle`_ driver, version 4.3.1 or newer.
+operators. You will also need the `cx_Oracle`_ driver, version 4.3.1 or newer.
 
 .. _`Oracle Database Server`: http://www.oracle.com/
 .. _`cx_Oracle`: http://cx-oracle.sourceforge.net/
 
-To run ``python manage.py syncdb``, you'll need to create an Oracle database
+In order for the ``python manage.py syncdb`` command to work, your Oracle
-user with CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE, and CREATE TRIGGER
+database user must have privileges to run the following commands:
-privileges.  To run Django's test suite, the user also needs 
-CREATE and DROP DATABASE and CREATE and DROP TABLESPACE privileges.
 
-Connecting to the Database
+	* CREATE TABLE
+	* CREATE SEQUENCE
+	* CREATE PROCEDURE
+	* CREATE TRIGGER
+
+To run Django's test suite, the user needs these *additional* privileges:
+
+ 	* CREATE DATABASE
+	* DROP DATABASE
+	* CREATE TABLESPACE
+	* DROP TABLESPACE
+
+Connecting to the database
 --------------------------
 
 Your Django settings.py file should look something like this for Oracle::
@@ -213,29 +223,29 @@ and ``DATABASE_PORT`` like so::
 You should supply both ``DATABASE_HOST`` and ``DATABASE_PORT``, or leave both
 as empty strings.
 
-Tablespace Options
+Tablespace options
 ------------------
 
 A common paradigm for optimizing performance in Oracle-based systems is the
 use of `tablespaces`_ to organize disk layout. The Oracle backend supports
 this use case by adding ``db_tablespace`` options to the ``Meta`` and
-``Field`` classes.  (When using a backend that lacks support for tablespaces,
+``Field`` classes.  (When you use a backend that lacks support for tablespaces,
-these options are ignored.)
+Django ignores these options.)
 
 .. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace
 
 A tablespace can be specified for the table(s) generated by a model by
-supplying the ``db_tablespace`` option inside the model's ``Meta`` class.
+supplying the ``db_tablespace`` option inside the model's ``class Meta``.
-Additionally, the ``db_tablespace`` option can be passed to a ``Field``
+Additionally, you can pass the ``db_tablespace`` option to a ``Field``
 constructor to specify an alternate tablespace for the ``Field``'s column
-index.  If no index would be created for the column, the ``db_tablespace``
+index. If no index would be created for the column, the ``db_tablespace``
 option is ignored.
 
 ::
 
     class TablespaceExample(models.Model):
-        name = models.CharField(maxlength=30, db_index=True, db_tablespace="indexes")
+        name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes")
-        data = models.CharField(maxlength=255, db_index=True)
+        data = models.CharField(max_length=255, db_index=True)
         edges = models.ManyToManyField(to="self", db_tablespace="indexes")
 
         class Meta:
@@ -243,46 +253,46 @@ option is ignored.
 
 In this example, the tables generated by the ``TablespaceExample`` model
 (i.e., the model table and the many-to-many table) would be stored in the
-``tables`` tablespace.  The index for the name field and the indexes on the
+``tables`` tablespace. The index for the name field and the indexes on the
-many-to-many table would be stored in the ``indexes`` tablespace.  The ``data``
+many-to-many table would be stored in the ``indexes`` tablespace. The ``data``
 field would also generate an index, but no tablespace for it is specified, so
 it would be stored in the model tablespace ``tables`` by default.
 
-Django does not create the tablespaces for you.  Please refer to `Oracle's
+Django does not create the tablespaces for you. Please refer to `Oracle's
 documentation`_ for details on creating and managing tablespaces.
 
 .. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403
 
-Naming Issues
+Naming issues
 -------------
 
-Oracle imposes a name length limit of 30 characters.  To accommodate this, the
+Oracle imposes a name length limit of 30 characters. To accommodate this, the
 backend truncates database identifiers to fit, replacing the final four
 characters of the truncated name with a repeatable MD5 hash value.
 
-NULL and Empty Strings
+NULL and empty strings
 ----------------------
 
 Django generally prefers to use the empty string ('') rather than NULL, but
-Oracle treats both identically.  To get around this, the Oracle backend
+Oracle treats both identically. To get around this, the Oracle backend
 coerces the ``null=True`` option on fields that permit the empty string as a
-value.  When fetching from the database, it is assumed that a NULL value in
+value. When fetching from the database, it is assumed that a NULL value in
 one of these fields really means the empty string, and the data is silently
 converted to reflect this assumption.
 
-TextField Limitations
+``TextField`` limitations
----------------------
+-------------------------
 
-The Oracle backend stores ``TextFields`` as ``NCLOB`` columns.  Oracle imposes
+The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes
 some limitations on the usage of such LOB columns in general:
 
   * LOB columns may not be used as primary keys.
 
   * LOB columns may not be used in indexes.
 
-  * LOB columns may not be used in a ``SELECT DISTINCT`` list.  This means that
+  * LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that
     attempting to use the ``QuerySet.distinct`` method on a model that
     includes ``TextField`` columns will result in an error when run against
-    Oracle.  A workaround to this is to keep ``TextField`` columns out of any
+    Oracle. A workaround to this is to keep ``TextField`` columns out of any
-    models that you foresee performing ``.distinct`` queries on, and to
+    models that you foresee performing ``distinct()`` queries on, and to
     include the ``TextField`` in a related model instead.