schema-evolution: merged trunk:HEAD into schema-evolution branch

git-svn-id: http://code.djangoproject.com/svn/django/branches/schema-evolution@5734 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 59 insertions, 20 deletions

diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 1113b603da..180e30292d 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -10,14 +10,23 @@ 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
 ``import django``. If that command runs successfully, with no errors, Django is
 installed.
 
-.. _`Django installed`: http://www.djangoproject.com/documentation/install/
+.. _`Django installed`: ../install/
+
+.. admonition:: Where to get help:
+
+    If you're having trouble going through this tutorial, please post a message
+    to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll
+    try to help.
+
+.. _django-users: http://groups.google.com/group/django-users
+.. _#django: irc://irc.freenode.net/django
 
 Creating a project
 ==================
@@ -32,6 +41,13 @@ From the command line, ``cd`` into a directory where you'd like to store your
 code, then run the command ``django-admin.py startproject mysite``. This
 will create a ``mysite`` directory in your current directory.
 
+.. note::
+
+    You'll need to avoid naming projects after built-in Python or Django
+    components. In particular, this means you should avoid using names like
+    ``django`` (which will conflict with Django itself) or ``site`` (which
+    conflicts with a built-in Python package).
+
 (``django-admin.py`` should be on your system path if you installed Django via
 ``python setup.py``. If it's not on your path, you can find it in
 ``site-packages/django/bin``, where ``site-packages`` is a directory within
@@ -108,7 +124,7 @@ It worked!
 
     Full docs for the development server are at `django-admin documentation`_.
 
-.. _django-admin documentation: http://www.djangoproject.com/documentation/django_admin/
+.. _django-admin documentation: ../django-admin/
 
 Database setup
 --------------
@@ -117,8 +133,8 @@ Now, edit ``settings.py``. It's a normal Python module with module-level
 variables representing Django settings. Change these settings to match your
 database's connection parameters:
 
-    * ``DATABASE_ENGINE`` -- Either 'postgresql', 'mysql' or 'sqlite3'.
-      More coming soon.
+    * ``DATABASE_ENGINE`` -- Either 'postgresql_psycopg2', 'mysql' or 'sqlite3'.
+      Other backends are `also available`_.
     * ``DATABASE_NAME`` -- The name of your database, or the full (absolute)
       path to the database file if you're using SQLite.
     * ``DATABASE_USER`` -- Your database username (not used for SQLite).
@@ -127,6 +143,8 @@ database's connection parameters:
       empty string if your database server is on the same physical machine
       (not used for SQLite).
 
+.. _also available: ../settings/
+
 .. admonition:: Note
 
     If you're using PostgreSQL or MySQL, make sure you've created a database by
@@ -303,7 +321,8 @@ Now Django knows ``mysite`` includes the ``polls`` app. Let's run another comman
 
     python manage.py sql polls
 
-You should see the following (the CREATE TABLE SQL statements for the polls app)::
+You should see something similar to the following (the CREATE TABLE SQL statements
+for the polls app)::
 
     BEGIN;
     CREATE TABLE "polls_poll" (
@@ -321,6 +340,8 @@ You should see the following (the CREATE TABLE SQL statements for the polls app)
 
 Note the following:
 
+    * The exact output will vary depending on the database you are using.
+
     * Table names are automatically generated by combining the name of the app
       (``polls``) and the lowercase name of the model -- ``poll`` and
       ``choice``. (You can override this behavior.)
@@ -339,7 +360,7 @@ Note the following:
       quotes. The author of this tutorial runs PostgreSQL, so the example
       output is in PostgreSQL syntax.
 
-    * The `sql` command doesn't actually run the SQL in your database - it just
+    * The ``sql`` command doesn't actually run the SQL in your database - it just
       prints it to the screen so that you can see what SQL Django thinks is required.
       If you wanted to, you could copy and paste this SQL into your database prompt.
       However, as we will see shortly, Django provides an easier way of committing
@@ -349,8 +370,9 @@ If you're interested, also run the following commands:
     * ``python manage.py validate polls`` -- Checks for any errors in the
       construction of your models.
 
-    * ``python manage.py sqlinitialdata polls`` -- Outputs any initial data
-      required for Django's admin framework and your models.
+    * ``python manage.py sqlcustom polls`` -- Outputs any custom SQL statements
+      (such as table modifications or constraints) that are defined for the
+      application.
 
     * ``python manage.py sqlclear polls`` -- Outputs the necessary ``DROP
       TABLE`` statements for this app, according to which tables already exist
@@ -360,7 +382,7 @@ If you're interested, also run the following commands:
       statements for this app.
 
     * ``python manage.py sqlall polls`` -- A combination of all the SQL from
-      the 'sql', 'sqlinitialdata', and 'sqlindexes' commands.
+      the 'sql', 'sqlcustom', and 'sqlindexes' commands.
 
 Looking at the output of those commands can help you understand what's actually
 happening under the hood.
@@ -378,7 +400,7 @@ as you like, and it will only ever create the tables that don't exist.
 Read the `django-admin.py documentation`_ for full information on what the
 ``manage.py`` utility can do.
 
-.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/
+.. _django-admin.py documentation: ../django-admin/
 
 Playing with the API
 ====================
@@ -452,22 +474,39 @@ Once you're in the shell, explore the database API::
 
 Wait a minute. ``<Poll: Poll object>`` is, utterly, an unhelpful
 representation of this object. Let's fix that by editing the polls model (in
-the ``polls/models.py`` file) and adding a ``__str__()`` method to both
+the ``polls/models.py`` file) and adding a ``__unicode__()`` method to both
 ``Poll`` and ``Choice``::
 
     class Poll(models.Model):
         # ...
-        def __str__(self):
+        def __unicode__(self):
             return self.question
 
     class Choice(models.Model):
         # ...
-        def __str__(self):
+        def __unicode__(self):
             return self.choice
 
-It's important to add ``__str__()`` methods to your models, not only for your
-own sanity when dealing with the interactive prompt, but also because objects'
-representations are used throughout Django's automatically-generated admin.
+It's important to add ``__unicode__()`` methods to your models, not only for
+your own sanity when dealing with the interactive prompt, but also because
+objects' representations are used throughout Django's automatically-generated
+admin.
+
+.. admonition:: Why ``__unicode__()`` and not ``__str__()``?
+
+    If you're familiar with Python, you might be in the habit of adding
+    ``__str__()`` methods to your classes, not ``__unicode__()`` methods.
+    We use ``__unicode__()`` here because Django models deal with Unicode by
+    default. All data stored in your database is converted to Unicode when it's
+    returned.
+
+    Django models have a default ``__str__()`` method that calls
+    ``__unicode__()`` and converts the result to a UTF-8 bytestring. This means
+    that ``unicode(p)`` will return a Unicode string, and ``str(p)`` will return
+    a normal string, with characters encoded as UTF-8.
+
+    If all of this is jibberish to you, just remember to add ``__unicode__()``
+    methods to your models. With any luck, things should Just Work for you.
 
 Note these are normal Python methods. Let's add a custom method, just for
 demonstration::
@@ -487,7 +526,7 @@ Let's jump back into the Python interactive shell by running
 
     >>> from mysite.polls.models import Poll, Choice
 
-    # Make sure our __str__() addition worked.
+    # Make sure our __unicode__() addition worked.
     >>> Poll.objects.all()
     [<Poll: What's up?>]
 
@@ -555,5 +594,5 @@ For full details on the database API, see our `Database API reference`_.
 When you're comfortable with the API, read `part 2 of this tutorial`_ to get
 Django's automatic admin working.
 
-.. _Database API reference: http://www.djangoproject.com/documentation/db_api/
-.. _part 2 of this tutorial: http://www.djangoproject.com/documentation/tutorial2/
+.. _Database API reference: ../db-api/
+.. _part 2 of this tutorial: ../tutorial02/