Edited some docs and docstrings until [17685]

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

django/contrib/auth/management/commands/changepassword.py

@@ -9,8 +9,7 @@ from django.db import DEFAULT_DB_ALIAS
 class Command(BaseCommand):
     option_list = BaseCommand.option_list + (
         make_option('--database', action='store', dest='database',
-            default=DEFAULT_DB_ALIAS, help='Nominates a database to query for the user. '
+            default=DEFAULT_DB_ALIAS, help='Specifies the database to use. Default is "default".'),
-                    'Defaults to the "default" database.'),
     )
     help = "Change a user's password for django.contrib.auth."
 

django/contrib/auth/management/commands/createsuperuser.py

@@ -39,8 +39,7 @@ class Command(BaseCommand):
                   'superusers created with --noinput will not be able to log '
                   'in until they\'re given a valid password.')),
         make_option('--database', action='store', dest='database',
-            default=DEFAULT_DB_ALIAS, help='Nominates a database to save the user to. '
+            default=DEFAULT_DB_ALIAS, help='Specifies the database to use. Default is "default".'),
-                    'Defaults to the "default" database.'),
     )
     help = 'Used to create a superuser.'
 

docs/ref/django-admin.txt

@@ -1199,8 +1199,8 @@ change the password whose username matches the current user.
 
 .. versionadded:: 1.4
 
-The ``--database`` option can be used to specify the database to query for the
+Use the ``--database`` option to specify the database to query for the user. If
-user. If it is not supplied the ``default`` database will be used.
+it's not supplied, Django will use the ``default`` database.
 
 Example usage::
 
@@ -1234,8 +1234,8 @@ it when running interactively.
 
 .. versionadded:: 1.4
 
-The ``--database`` option can be used to specify the database into which the
+Use the ``--database`` option to specify the database into which the superuser
-superuser object will be saved.
+object will be saved.
 
 ``django.contrib.gis``
 ----------------------

docs/ref/models/querysets.txt

@@ -1377,7 +1377,7 @@ This has a number of caveats though:
     maximum is defined by the SQLITE_MAX_VARIABLE_NUMBER_ compilation option,
     which defaults to 999. For instance, if your model has 8 fields (including
     the primary key), you cannot create more than 999 // 8 = 124 instances at
-    a time. If you exceed this limit, you will get an exception::
+    a time. If you exceed this limit, you'll get an exception::
 
         django.db.utils.DatabaseError: too many SQL variables
 

docs/releases/1.4.txt

@@ -617,9 +617,9 @@ Django 1.4 also includes several smaller improvements worth noting:
 
 * A new :class:`django.test.SimpleTestCase` subclass of
   :class:`unittest.TestCase`
-  that is comparatively lighter than :class:`django.test.TestCase` and
+  that's lighter than :class:`django.test.TestCase` and company. It can be
-  company. It can be useful in testing scenarios where e.g. no database
+  useful in tests that don't need to hit a database. See
-  interaction is needed. See :ref:`testcase_hierarchy_diagram`.
+  :ref:`testcase_hierarchy_diagram`.
 
 Backwards incompatible changes in 1.4
 =====================================

docs/topics/i18n/timezones.txt

@@ -12,22 +12,22 @@ Overview
 ========
 
 When support for time zones is enabled, Django stores date and time
-information in UTC in the database, uses time zone-aware datetime objects
+information in UTC in the database, uses time-zone-aware datetime objects
 internally, and translates them to the end user's time zone in templates and
 forms.
 
 This is handy if your users live in more than one time zone and you want to
-display date and time information according to each user's wall clock. Even if
+display date and time information according to each user's wall clock.
-your website is available in only one time zone, it's still a good practice to
-store data in UTC in your database. Here is why.
 
-Many countries have a system of daylight saving time (DST), where clocks are
+Even if your Web site is available in only one time zone, it's still good
-moved forwards in spring and backwards in autumn. If you're working in local
+practice to store data in UTC in your database. One main reason is Daylight
-time, you're likely to encounter errors twice a year, when the transitions
+Saving Time (DST). Many countries have a system of DST, where clocks are moved
-happen. The pytz_ documentation discusses `these issues`_ in greater detail.
+forward in spring and backward in autumn. If you're working in local time,
-It probably doesn't matter for your blog, but it's more annoying if you
+you're likely to encounter errors twice a year, when the transitions happen.
-over-bill or under-bill your customers by one hour, twice a year, every year.
+(The pytz_ documentation discusses `these issues`_ in greater detail.) This
-The solution to this problem is to use UTC in the code and local time only when
+probably doesn't matter for your blog, but it's a problem if you over-bill or
+under-bill your customers by one hour, twice a year, every year. The solution
+to this problem is to use UTC in the code and use local time only when
 interacting with end users.
 
 Time zone support is disabled by default. To enable it, set :setting:`USE_TZ =
@@ -47,10 +47,10 @@ but not mandatory. It's as simple as:
 .. note::
 
     There is also an independent but related :setting:`USE_L10N` setting that
-    controls if Django should activate format localization. See
+    controls whether Django should activate format localization. See
     :doc:`/topics/i18n/formatting` for more details.
 
-If you're stumbling on a particular problem, start with the :ref:`time zone
+If you're wrestling with a particular problem, start with the :ref:`time zone
 FAQ <time-zones-faq>`.
 
 Concepts
@@ -62,11 +62,11 @@ Naive and aware datetime objects
 Python's :class:`datetime.datetime` objects have a ``tzinfo`` attribute that
 can be used to store time zone information, represented as an instance of a
 subclass of :class:`datetime.tzinfo`. When this attribute is set and describes
-an offset, a datetime object is **aware**; otherwise, it's **naive**.
+an offset, a datetime object is **aware**. Otherwise, it's **naive**.
 
 You can use :func:`~django.utils.timezone.is_aware` and
-:func:`~django.utils.timezone.is_naive` to determine if datetimes are aware or
+:func:`~django.utils.timezone.is_naive` to determine whether datetimes are
-naive.
+aware or naive.
 
 When time zone support is disabled, Django uses naive datetime objects in local
 time. This is simple and sufficient for many use cases. In this mode, to obtain
@@ -76,7 +76,7 @@ the current time, you would write::
 
     now = datetime.datetime.now()
 
-When time zone support is enabled, Django uses time zone aware datetime
+When time zone support is enabled, Django uses time-zone-aware datetime
 objects. If your code creates datetime objects, they should be aware too. In
 this mode, the example above becomes::
 
@@ -173,7 +173,7 @@ time zone automatically. Instead, Django provides :ref:`time zone selection
 functions <time-zone-selection-functions>`. Use them to build the time zone
 selection logic that makes sense for you.
 
-Most websites who care about time zones just ask users in which time zone they
+Most Web sites that care about time zones just ask users in which time zone they
 live and store this information in the user's profile. For anonymous users,
 they use the time zone of their primary audience or UTC. pytz_ provides
 helpers_, like a list of time zones per country, that you can use to pre-select
@@ -481,9 +481,9 @@ Setup
 
    Yes. When time zone support is enabled, Django uses a more accurate model
    of local time. This shields you from subtle and unreproducible bugs around
-   daylight saving time (DST) transitions. Remember that your website runs 24/7!
+   Daylight Saving Time (DST) transitions.
 
-   In this regard, time zones is comparable to ``unicode`` in Python. At first
+   In this regard, time zones are comparable to ``unicode`` in Python. At first
    it's hard. You get encoding and decoding errors. Then you learn the rules.
    And some problems disappear -- you never get mangled output again when your
    application receives non-ASCII input.
@@ -501,14 +501,14 @@ Setup
    For these reasons, time zone support is enabled by default in new projects,
    and you should keep it unless you have a very good reason not to.
 
-2. **I've enabled time zone support, am I safe?**
+2. **I've enabled time zone support. Am I safe?**
 
    Maybe. You're better protected from DST-related bugs, but you can still
    shoot yourself in the foot by carelessly turning naive datetimes into aware
    datetimes, and vice-versa.
 
-   If your application connects to other systems, for instance if it queries
+   If your application connects to other systems -- for instance, if it queries
-   a webservice, make sure datetimes are properly specified. To transmit
+   a Web service -- make sure datetimes are properly specified. To transmit
    datetimes safely, their representation should include the UTC offset, or
    their values should be in UTC (or both!).
 
@@ -549,8 +549,7 @@ Troubleshooting
 1. **My application crashes with** ``TypeError: can't compare offset-naive``
    ``and offset-aware datetimes`` **-- what's wrong?**
 
-   First, don't panic. Then, let's reproduce this error, simply by comparing a
+   Let's reproduce this error by comparing a naive and an aware datetime::
-   naive and an aware datetime::
 
        >>> import datetime
        >>> from django.utils import timezone
@@ -561,10 +560,11 @@ Troubleshooting
        ...
        TypeError: can't compare offset-naive and offset-aware datetimes
 
-   If you encounter this error, most likely, your code is comparing:
+   If you encounter this error, most likely your code is comparing these two
+   things:
 
-   - a datetime provided by Django, for instance a value read from a form or
+   - a datetime provided by Django -- for instance, a value read from a form or
-     a model field: since you enabled time zone support, it is aware;
+     a model field. Since you enabled time zone support, it's aware.
    - a datetime generated by your code, which is naive (or you wouldn't be
      reading this).
 
@@ -575,12 +575,12 @@ Troubleshooting
    independently of the value of :setting:`USE_TZ`, you may find
    :func:`django.utils.timezone.now` useful. This function returns the current
    date and time as a naive datetime when ``USE_TZ = False`` and as an aware
-   datetime when ``USE_TZ = True``. You can add or substract
+   datetime when ``USE_TZ = True``. You can add or subtract
    :class:`datetime.timedelta` as needed.
 
 2. **I see lots of** ``RuntimeWarning: DateTimeField received a naive
    datetime`` ``(YYYY-MM-DD HH:MM:SS)`` ``while time zone support is active``
-   **-- is it bad?**
+   **-- is that bad?**
 
    When time zone support is enabled, the database layer expects to receive
    only aware datetimes from your code. This warning occurs when it receives a
@@ -617,15 +617,14 @@ Troubleshooting
        datetime.datetime(2012, 3, 2, 19, 30, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)
 
    As this example shows, the same datetime has a different date, depending on
-   the time zone in which it is representend. But the real problem is more
+   the time zone in which it is represented. But the real problem is more
    fundamental.
 
    A datetime represents a **point in time**. It's absolute: it doesn't depend
-   on anything (barring relativistic effects). On the contrary, a date is a
+   on anything. On the contrary, a date is a **calendaring concept**. It's a
-   **calendaring concept**. It's a period of time whose bounds depend on the
+   period of time whose bounds depend on the time zone in which the date is
-   time zone in which the date is considered. As you can see, these two
+   considered. As you can see, these two concepts are fundamentally different,
-   concepts are fundamentally different and converting a datetime to a date
+   and converting a datetime to a date isn't a deterministic operation.
-   isn't a deterministic operation.
 
    What does this mean in practice?
 
@@ -633,7 +632,7 @@ Troubleshooting
    :class:`~datetime.date`. For instance, you can use the :tfilter:`date`
    template filter to only show the date part of a datetime. This filter will
    convert the datetime into the current time zone before formatting it,
-   ensuring the results appear correct for the user.
+   ensuring the results appear correctly.
 
    If you really need to do the conversion yourself, you must ensure the
    datetime is converted to the appropriate time zone first. Usually, this
@@ -654,7 +653,7 @@ Troubleshooting
 Usage
 -----
 
-1. **I have this string** ``"2012-02-21 10:28:45"`` **and I know it's in the**
+1. **I have a string** ``"2012-02-21 10:28:45"`` **and I know it's in the**
    ``"Europe/Helsinki"`` **time zone. How do I turn that into an aware
    datetime?**
 
@@ -668,7 +667,7 @@ Usage
 
    Note that ``localize`` is a pytz extension to the :class:`~datetime.tzinfo`
    API. Also, you may want to catch :exc:`~pytz.InvalidTimeError`. The
-   documentation of pytz contains `more examples`_; you should review it
+   documentation of pytz contains `more examples`_. You should review it
    before attempting to manipulate aware datetimes.
 
 2. **How can I obtain the current time in the local time zone?**
@@ -685,8 +684,8 @@ Usage
    the datetime in UTC returned by :func:`django.utils.timezone.now` will be
    sufficient.
 
-   For the sake of completeness, if you really wanted the current time in the
+   For the sake of completeness, though, if you really wanted the current time
-   local time zone, here's how you would obtain it::
+   in the local time zone, here's how you would obtain it::
 
        >>> import datetime
        >>> from django.utils import timezone

docs/topics/install.txt

@@ -210,17 +210,19 @@ Installing an official release with ``pip``
 This is the recommended way to install Django.
 
 1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
-   distribution has ``pip`` already installed, make sure it isn't too outdated.
+   distribution already has ``pip`` installed, you might need to update it if
+   it's outdated. (If it's outdated, you'll know because installation won't
+   work.)
 
 2. (optional) Take a look at virtualenv_ and virtualenvwrapper_. These tools
    provide isolated Python environments, which are more practical than
-   installing packages system-wide. They also allow installing packages
+   installing packages systemwide. They also allow installing packages
    without administrator privileges. It's up to you to decide if you want to
    learn and use them.
 
 3. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
    command ``sudo pip install Django`` at the shell prompt. If you're using
-   Windows, start up a command shell with administrator privileges and run
+   Windows, start a command shell with administrator privileges and run
    the command ``pip install Django``. This will install Django in your Python
    installation's ``site-packages`` directory.
 
@@ -228,7 +230,6 @@ This is the recommended way to install Django.
    privileges, and this will install Django in the virtualenv's
    ``site-packages`` directory.
 
-
 .. _pip: http://www.pip-installer.org/
 .. _virtualenv: http://www.virtualenv.org/
 .. _virtualenvwrapper: http://www.doughellmann.com/docs/virtualenvwrapper/
@@ -248,7 +249,7 @@ Installing an official release manually
 
 4. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
    command ``sudo python setup.py install`` at the shell prompt. If you're
-   using Windows, start up a command shell with administrator privileges and
+   using Windows, start a command shell with administrator privileges and
    run the command ``python setup.py install``. This will install Django in
    your Python installation's ``site-packages`` directory.
 
@@ -343,7 +344,7 @@ latest bug fixes and improvements, follow these instructions:
 
 .. warning::
 
-    You mustn't run ``sudo python setup.py install``, because you've already
+    Don't run ``sudo python setup.py install``, because you've already
     carried out the equivalent actions in steps 3 and 4. Furthermore, this is
     known to cause problems when updating to a more recent version of Django.
 

tests/regressiontests/delete_regress/tests.py

@@ -152,7 +152,7 @@ class LargeDeleteTests(TestCase):
 
 class ProxyDeleteTest(TestCase):
     """
-    Tests on_delete behaviour for proxy models. Deleting the *proxy*
+    Tests on_delete behavior for proxy models. Deleting the *proxy*
     instance bubbles through to its non-proxy and *all* referring objects
     are deleted.
 
@@ -188,7 +188,7 @@ class ProxyDeleteTest(TestCase):
 
 class ProxyOfProxyDeleteTest(ProxyDeleteTest):
     """
-    Tests on_delete behaviour for proxy-of-proxy models. Deleting the *proxy*
+    Tests on_delete behavior for proxy-of-proxy models. Deleting the *proxy*
     instance should bubble through to its proxy and non-proxy variants.
     Deleting *all* referring objects.
 
@@ -224,7 +224,7 @@ class ProxyOfProxyDeleteTest(ProxyDeleteTest):
 
 class ProxyParentDeleteTest(ProxyDeleteTest):
     """
-    Tests on_delete cascade behaviour for proxy models. Deleting the
+    Tests on_delete cascade behavior for proxy models. Deleting the
     *non-proxy* instance of a model should delete objects referencing the
     proxy.