19 files changed, 109 insertions, 106 deletions

diff --git a/docs/howto/apache-auth.txt b/docs/howto/apache-auth.txt
index 8fd3da2612..b3723f92c6 100644
--- a/docs/howto/apache-auth.txt
+++ b/docs/howto/apache-auth.txt
@@ -1,12 +1,17 @@
-.. _howto-apache-auth:
-
 =========================================================
 Authenticating against Django's user database from Apache
 =========================================================
 
+.. warning::
+
+    Support for mod_python has been deprecated within Django. At that
+    time, this method of authentication will no longer be provided by
+    Django. The community is welcome to offer its own alternate
+    solutions using WSGI middleware or other approaches.
+
 Since keeping multiple authentication databases in sync is a common problem when
 dealing with Apache, you can configuring Apache to authenticate against Django's
-:ref:`authentication system <topics-auth>` directly. For example, you
+:doc:`authentication system </topics/auth>` directly. For example, you
 could:
 
     * Serve static/media files directly from Apache only to authenticated users.
diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt
index f0e83c0ba5..9dbde29e5c 100644
--- a/docs/howto/auth-remote-user.txt
+++ b/docs/howto/auth-remote-user.txt
@@ -1,5 +1,3 @@
-.. _howto-auth-remote-user:
-
 ====================================
 Authentication using ``REMOTE_USER``
 ====================================
diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt
index 5005feaa80..1b0f32fb3f 100644
--- a/docs/howto/custom-file-storage.txt
+++ b/docs/howto/custom-file-storage.txt
@@ -1,5 +1,3 @@
-.. _howto-custom-file-storage:
-
 Writing a custom storage system
 ===============================
 
@@ -37,7 +35,7 @@ You'll need to follow these steps:
    the ``path()`` method.
 
 Your custom storage system may override any of the storage methods explained in
-:ref:`ref-files-storage`, but you **must** implement the following methods:
+:doc:`/ref/files/storage`, but you **must** implement the following methods:
 
     * :meth:`Storage.delete`
     * :meth:`Storage.exists`
@@ -63,7 +61,7 @@ backend storage system.
 
 Called by ``Storage.save()``. The ``name`` will already have gone through
 ``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a
-``File`` object itself. 
+``File`` object itself.
 
 Should return the actual name of name of the file saved (usually the ``name``
 passed in, but if the storage needs to change the file name return the new name
diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt
index f8b173cafa..7b25d6bdbe 100644
--- a/docs/howto/custom-management-commands.txt
+++ b/docs/howto/custom-management-commands.txt
@@ -1,5 +1,3 @@
-.. _howto-custom-management-commands:
-
 ====================================
 Writing custom django-admin commands
 ====================================
@@ -8,9 +6,9 @@ Writing custom django-admin commands
 
 Applications can register their own actions with ``manage.py``. For example,
 you might want to add a ``manage.py`` action for a Django app that you're
-distributing. In this document, we will be building a custom ``closepoll`` 
+distributing. In this document, we will be building a custom ``closepoll``
 command for the ``polls`` application from the
-:ref:`tutorial<intro-tutorial01>`.
+:doc:`tutorial</intro/tutorial01>`.
 
 To do this, just add a ``management/commands`` directory to the application.
 Each Python module in that directory will be auto-discovered and registered as
@@ -62,15 +60,22 @@ look like this:
                 poll.opened = False
                 poll.save()
 
-                print 'Successfully closed poll "%s"' % poll_id
+                self.stdout.write('Successfully closed poll "%s"\n' % poll_id)
+
+.. note::
+    When you are using management commands and wish to provide console
+    output, you should write to ``self.stdout`` and ``self.stderr``,
+    instead of printing to ``stdout`` and ``stderr`` directly. By
+    using these proxies, it becomes much easier to test your custom
+    command.
 
-The new custom command can be called using ``python manage.py closepoll 
+The new custom command can be called using ``python manage.py closepoll
 <poll_id>``.
 
 The ``handle()`` method takes zero or more ``poll_ids`` and sets ``poll.opened``
 to ``False`` for each one. If the user referenced any nonexistant polls, a
 :class:`CommandError` is raised. The ``poll.opened`` attribute does not exist
-in the :ref:`tutorial<intro-tutorial01>` and was added to
+in the :doc:`tutorial</intro/tutorial01>` and was added to
 ``polls.models.Poll`` for this example.
 
 The same ``closepoll`` could be easily modified to delete a given poll instead
@@ -91,8 +96,8 @@ must be added to :attr:`~BaseCommand.option_list` like this:
             )
         # ...
 
-In addition to being able to add custom command line options, all 
-:ref:`management commands<ref-django-admin>` can accept some 
+In addition to being able to add custom command line options, all
+:doc:`management commands</ref/django-admin>` can accept some
 default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
 
 Command objects
@@ -113,7 +118,7 @@ Subclassing the :class:`BaseCommand` class requires that you implement the
 Attributes
 ----------
 
-All attributes can be set in your derived class and can be used in 
+All attributes can be set in your derived class and can be used in
 :class:`BaseCommand`'s :ref:`subclasses<ref-basecommand-subclasses>`.
 
 .. attribute:: BaseCommand.args
@@ -133,7 +138,7 @@ All attributes can be set in your derived class and can be used in
 .. attribute:: BaseCommand.help
 
   A short description of the command, which will be printed in the
-  help message when the user runs the command 
+  help message when the user runs the command
   ``python manage.py help <command>``.
 
 .. attribute:: BaseCommand.option_list
@@ -230,7 +235,7 @@ Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement
 A command which takes no arguments on the command line.
 
 Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement
-:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is 
+:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is
 overridden to ensure no arguments are passed to the command.
 
 .. method:: NoArgsCommand.handle_noargs(**options)
diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index 90851459c1..fa4c07fed2 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -1,5 +1,3 @@
-.. _howto-custom-model-fields:
-
 ===========================
 Writing custom model fields
 ===========================
@@ -10,7 +8,7 @@ Writing custom model fields
 Introduction
 ============
 
-The :ref:`model reference <topics-db-models>` documentation explains how to use
+The :doc:`model reference </topics/db/models>` documentation explains how to use
 Django's standard field classes -- :class:`~django.db.models.CharField`,
 :class:`~django.db.models.DateField`, etc. For many purposes, those classes are
 all you'll need. Sometimes, though, the Django version won't meet your precise
@@ -109,7 +107,7 @@ What does a field class do?
 ---------------------------
 
 All of Django's fields (and when we say *fields* in this document, we always
-mean model fields and not :ref:`form fields <ref-forms-fields>`) are subclasses
+mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
 of :class:`django.db.models.Field`. Most of the information that Django records
 about a field is common to all fields -- name, help text, uniqueness and so
 forth. Storing all that information is handled by ``Field``. We'll get into the
@@ -124,7 +122,7 @@ when the model class is created (the precise details of how this is done are
 unimportant here). This is because the field classes aren't necessary when
 you're just creating and modifying attributes. Instead, they provide the
 machinery for converting between the attribute value and what is stored in the
-database or sent to the :ref:`serializer <topics-serialization>`.
+database or sent to the :doc:`serializer </topics/serialization>`.
 
 Keep this in mind when creating your own custom fields. The Django ``Field``
 subclass you write provides the machinery for converting between your Python
@@ -209,8 +207,8 @@ parameters:
     * :attr:`~django.db.models.Field.default`
     * :attr:`~django.db.models.Field.editable`
     * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
-      not be serialized when the model is passed to Django's :ref:`serializers
-      <topics-serialization>`. Defaults to ``True``.
+      not be serialized when the model is passed to Django's :doc:`serializers
+      </topics/serialization>`. Defaults to ``True``.
     * :attr:`~django.db.models.Field.unique_for_date`
     * :attr:`~django.db.models.Field.unique_for_month`
     * :attr:`~django.db.models.Field.unique_for_year`
@@ -225,8 +223,8 @@ parameters:
       inheritance. For advanced use only.
 
 All of the options without an explanation in the above list have the same
-meaning they do for normal Django fields. See the :ref:`field documentation
-<ref-models-fields>` for examples and details.
+meaning they do for normal Django fields. See the :doc:`field documentation
+</ref/models/fields>` for examples and details.
 
 The ``SubfieldBase`` metaclass
 ------------------------------
@@ -270,8 +268,8 @@ value. This means that whenever a value may be assigned to the field,
 you need to ensure that it will be of the correct datatype, or that
 you handle any exceptions.
 
-This is especially important if you use :ref:`ModelForms
-<topics-forms-modelforms>`. When saving a ModelForm, Django will use
+This is especially important if you use :doc:`ModelForms
+</topics/forms/modelforms>`. When saving a ModelForm, Django will use
 form values to instantiate model instances. However, if the cleaned
 form data can't be used as valid input to the field, the normal form
 validation process will break.
@@ -611,8 +609,8 @@ All of the ``kwargs`` dictionary is passed directly to the form field's
 :meth:`~django.forms.Field__init__` method. Normally, all you need to do is
 set up a good default for the ``form_class`` argument and then delegate further
 handling to the parent class. This might require you to write a custom form
-field (and even a form widget). See the :ref:`forms documentation
-<topics-forms-index>` for information about this, and take a look at the code in
+field (and even a form widget). See the :doc:`forms documentation
+</topics/forms/index>` for information about this, and take a look at the code in
 :mod:`django.contrib.localflavor` for some examples of custom widgets.
 
 Continuing our ongoing example, we can write the :meth:`formfield` method as::
@@ -721,7 +719,7 @@ Django provides a ``File`` class, which is used as a proxy to the file's
 contents and operations. This can be subclassed to customize how the file is
 accessed, and what methods are available. It lives at
 ``django.db.models.fields.files``, and its default behavior is explained in the
-:ref:`file documentation <ref-files-file>`.
+:doc:`file documentation </ref/files/file>`.
 
 Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
 told to use it. To do so, simply assign the new ``File`` subclass to the special
diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 1406d19b58..c4d2315bd4 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -1,5 +1,3 @@
-.. _howto-custom-template-tags:
-
 ================================
 Custom template tags and filters
 ================================
@@ -7,8 +5,8 @@ Custom template tags and filters
 Introduction
 ============
 
-Django's template system comes with a wide variety of :ref:`built-in
-tags and filters <ref-templates-builtins>` designed to address the
+Django's template system comes with a wide variety of :doc:`built-in
+tags and filters </ref/templates/builtins>` designed to address the
 presentation logic needs of your application. Nevertheless, you may
 find yourself needing functionality that is not covered by the core
 set of template primitives. You can extend the template engine by
diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt
index cf05174390..c2b8aa8b53 100644
--- a/docs/howto/deployment/fastcgi.txt
+++ b/docs/howto/deployment/fastcgi.txt
@@ -1,13 +1,11 @@
-.. _howto-deployment-fastcgi:
-
 ============================================
 How to use Django with FastCGI, SCGI, or AJP
 ============================================
 
 .. highlight:: bash
 
-Although the current preferred setup for running Django is :ref:`Apache with
-mod_wsgi <howto-deployment-modwsgi>`, many people use shared hosting, on
+Although the current preferred setup for running Django is :doc:`Apache with
+mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on
 which protocols such as FastCGI, SCGI or AJP are the only viable options. In
 some setups, these protocols may provide better performance than mod_wsgi_.
 
@@ -22,14 +20,14 @@ serve pages to a Web server. The Web server delegates the incoming Web requests
 (via a socket) to FastCGI, which executes the code and passes the response back
 to the Web server, which, in turn, passes it back to the client's Web browser.
 
-Like mod_python, FastCGI allows code to stay in memory, allowing requests to be
-served with no startup time. Unlike mod_python_ (or `mod_perl`_), a FastCGI
-process doesn't run inside the Web server process, but in a separate,
+Like mod_wsgi, FastCGI allows code to stay in memory, allowing requests to be
+served with no startup time. While mod_wsgi can either be configured embedded
+in the Apache webserver process or as a separate daemon process, a FastCGI
+process never runs inside the Web server process, always in a separate,
 persistent process.
 
 .. _mod_wsgi: http://code.google.com/p/modwsgi/
 .. _mod_perl: http://perl.apache.org/
-.. _mod_python: http://www.modpython.org/
 
 .. admonition:: Why run code in a separate process?
 
@@ -37,8 +35,7 @@ persistent process.
     languages (most notably PHP, Python and Perl) inside the process space of
     your Web server. Although this lowers startup time -- because code doesn't
     have to be read off disk for every request -- it comes at the cost of
-    memory use. For mod_python, for example, every Apache process gets its own
-    Python interpreter, which uses up a considerable amount of RAM.
+    memory use.
 
     Due to the nature of FastCGI, it's even possible to have processes that run
     under a different user account than the Web server process. That's a nice
@@ -74,7 +71,7 @@ TCP socket. What you choose is a manner of preference; a TCP socket is usually
 easier due to permissions issues.
 
 To start your server, first change into the directory of your project (wherever
-your :ref:`manage.py <ref-django-admin>` is), and then run the
+your :doc:`manage.py </ref/django-admin>` is), and then run the
 :djadmin:`runfcgi` command::
 
     ./manage.py runfcgi [options]
@@ -363,7 +360,7 @@ Serving admin media files
 
 Regardless of the server and configuration you eventually decide to use, you
 will also need to give some thought to how to serve the admin media files. The
-advice given in the :ref:`modpython <serving-the-admin-files>` documentation
+advice given in the :ref:`mod_wsgi <serving-the-admin-files>` documentation
 is also applicable in the setups detailed above.
 
 Forcing the URL prefix to a particular value
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
index 78cfb037f5..2eff3e6ace 100644
--- a/docs/howto/deployment/index.txt
+++ b/docs/howto/deployment/index.txt
@@ -1,5 +1,3 @@
-.. _howto-deployment-index:
-
 Deploying Django
 ================
 
@@ -10,18 +8,18 @@ ways to easily deploy Django:
 
 .. toctree::
    :maxdepth: 1
-   
+
    modwsgi
-   modpython
    fastcgi
-   
+   mod_python (deprecated) <modpython>
+
 If you're new to deploying Django and/or Python, we'd recommend you try
-:ref:`mod_wsgi <howto-deployment-modwsgi>` first. In most cases it'll be the easiest,
+:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
 fastest, and most stable deployment choice.
 
 .. seealso::
 
     * `Chapter 12 of The Django Book`_ discusses deployment and especially
       scaling in more detail.
-      
+
 .. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/
diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt
index 143a6d5ae3..a9b665f331 100644
--- a/docs/howto/deployment/modpython.txt
+++ b/docs/howto/deployment/modpython.txt
@@ -4,11 +4,18 @@
 How to use Django with Apache and mod_python
 ============================================
 
+.. warning::
+
+    Support for mod_python will be deprecated in a future release of Django. If
+    you are configuring a new deployment, you are strongly encouraged to
+    consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the
+    other :doc:`supported backends </howto/deployment/index>`.
+
 .. highlight:: apache
 
 The `mod_python`_ module for Apache_ can be used to deploy Django to a
 production server, although it has been mostly superseded by the simpler
-:ref:`mod_wsgi deployment option <howto-deployment-modwsgi>`.
+:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`.
 
 mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within
 Apache and loads Python code into memory when the server starts. Code stays in
@@ -25,8 +32,8 @@ Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
       Apache, there's no better source than `Apache's own official
       documentation`_
 
-    * You may also be interested in :ref:`How to use Django with FastCGI, SCGI,
-      or AJP <howto-deployment-fastcgi>`.
+    * You may also be interested in :doc:`How to use Django with FastCGI, SCGI,
+      or AJP </howto/deployment/fastcgi>`.
 
 .. _Apache: http://httpd.apache.org/
 .. _mod_python: http://www.modpython.org/
@@ -216,8 +223,6 @@ Or add the debugging information to the template of your page.
 
 .. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html
 
-.. _serving-media-files:
-
 Serving media files
 ===================
 
@@ -269,10 +274,6 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or
 .. _Apache: http://httpd.apache.org/
 .. _Cherokee: http://www.cherokee-project.com/
 
-.. _howto-deployment-modpython-serving-the-admin-files:
-
-.. _serving-the-admin-files:
-
 Serving the admin files
 =======================
 
@@ -383,7 +384,7 @@ If you get a UnicodeEncodeError
 ===============================
 
 If you're taking advantage of the internationalization features of Django (see
-:ref:`topics-i18n`) and you intend to allow users to upload files, you must
+:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must
 ensure that the environment used to start Apache is configured to accept
 non-ASCII file names. If your environment is not correctly configured, you
 will trigger ``UnicodeEncodeError`` exceptions when calling functions like
diff --git a/docs/howto/deployment/modwsgi.txt b/docs/howto/deployment/modwsgi.txt
index 12de53f53d..e873006af0 100644
--- a/docs/howto/deployment/modwsgi.txt
+++ b/docs/howto/deployment/modwsgi.txt
@@ -1,5 +1,3 @@
-.. _howto-deployment-modwsgi:
-
 ==========================================
 How to use Django with Apache and mod_wsgi
 ==========================================
@@ -55,6 +53,8 @@ just above the final ``import`` line to place your project on the path. Remember
 replace 'mysite.settings' with your correct settings file, and '/usr/local/django'
 with your own project's location.
 
+.. _serving-media-files:
+
 Serving media files
 ===================
 
@@ -108,6 +108,29 @@ in the mod_wsgi documentation on `hosting static files`_.
 
 .. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files
 
+.. _serving-the-admin-files:
+
+Serving the admin files
+=======================
+
+Note that the Django development server automagically serves admin media files,
+but this is not the case when you use any other server arrangement. You're
+responsible for setting up Apache, or whichever media server you're using, to
+serve the admin files.
+
+The admin files live in (:file:`django/contrib/admin/media`) of the Django
+distribution.
+
+Here are two recommended approaches:
+
+    1. Create a symbolic link to the admin media files from within your
+       document root. This way, all of your Django-related files -- code **and**
+       templates -- stay in one place, and you'll still be able to ``svn
+       update`` your code to get the latest admin templates, if they change.
+
+    2. Or, copy the admin media files so that they live within your Apache
+       document root.
+
 Details
 =======
 
diff --git a/docs/howto/error-reporting.txt b/docs/howto/error-reporting.txt
index 97842d7263..1ec009dd2a 100644
--- a/docs/howto/error-reporting.txt
+++ b/docs/howto/error-reporting.txt
@@ -1,5 +1,3 @@
-.. _howto-error-reporting:
-
 Error reporting via e-mail
 ==========================
 
@@ -30,8 +28,8 @@ the HTTP request that caused the error.
    to specify :setting:`EMAIL_HOST` and possibly
    :setting:`EMAIL_HOST_USER` and :setting:`EMAIL_HOST_PASSWORD`,
    though other settings may be also required depending on your mail
-   server's configuration. Consult :ref:`the Django settings
-   documentation <ref-settings>` for a full list of email-related
+   server's configuration. Consult :doc:`the Django settings
+   documentation </ref/settings>` for a full list of email-related
    settings.
 
 By default, Django will send email from root@localhost. However, some mail
diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt
index 853162aa70..6bec531177 100644
--- a/docs/howto/i18n.txt
+++ b/docs/howto/i18n.txt
@@ -1,5 +1,3 @@
-.. _howto-i18n:
-
 .. _using-translations-in-your-own-projects:
 
 ===============================================
@@ -46,7 +44,7 @@ To create message files, you use the :djadmin:`django-admin.py makemessages <mak
 tool. You only need to be in the same directory where the ``locale/`` directory
 is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
 to produce the binary ``.mo`` files that are used by ``gettext``. Read the
-:ref:`topics-i18n-localization` document for more details.
+:doc:`/topics/i18n/localization` document for more details.
 
 You can also run ``django-admin.py compilemessages --settings=path.to.settings``
 to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
diff --git a/docs/howto/index.txt b/docs/howto/index.txt
index c582c8ed17..49d0644034 100644
--- a/docs/howto/index.txt
+++ b/docs/howto/index.txt
@@ -1,11 +1,9 @@
-.. _howto-index:
-
 "How-to" guides
 ===============
 
 Here you'll find short answers to "How do I....?" types of questions. These
 how-to guides don't cover topics in depth -- you'll find that material in the
-:ref:`topics-index` and the :ref:`ref-index`. However, these guides will help
+:doc:`/topics/index` and the :doc:`/ref/index`. However, these guides will help
 you quickly accomplish common tasks.
 
 .. toctree::
diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt
index b071d6d529..cf3f65d299 100644
--- a/docs/howto/initial-data.txt
+++ b/docs/howto/initial-data.txt
@@ -1,5 +1,3 @@
-.. _howto-initial-data:
-
 =================================
 Providing initial data for models
 =================================
@@ -20,10 +18,10 @@ Providing initial data with fixtures
 
 A fixture is a collection of data that Django knows how to import into a
 database. The most straightforward way of creating a fixture if you've already
-got some data is to use the :djadmin:`manage.py dumpdata` command. Or, you can
-write fixtures by hand; fixtures can be written as XML, YAML, or JSON documents.
-The :ref:`serialization documentation <topics-serialization>` has more details
-about each of these supported :ref:`serialization formats
+got some data is to use the :djadmin:`manage.py dumpdata <dumpdata>` command.
+Or, you can write fixtures by hand; fixtures can be written as XML, YAML, or
+JSON documents. The :doc:`serialization documentation </topics/serialization>`
+has more details about each of these supported :ref:`serialization formats
 <serialization-formats>`.
 
 As an example, though, here's what a fixture for a simple ``Person`` model might
@@ -114,9 +112,9 @@ which will insert the desired data (e.g., properly-formatted
 ``INSERT`` statements separated by semicolons).
 
 The SQL files are read by the :djadmin:`sqlcustom`, :djadmin:`sqlreset`,
-:djadmin:`sqlall` and :djadmin:`reset` commands in :ref:`manage.py
-<ref-django-admin>`. Refer to the :ref:`manage.py documentation
-<ref-django-admin>` for more information.
+:djadmin:`sqlall` and :djadmin:`reset` commands in :doc:`manage.py
+</ref/django-admin>`. Refer to the :doc:`manage.py documentation
+</ref/django-admin>` for more information.
 
 Note that if you have multiple SQL data files, there's no guarantee of
 the order in which they're executed. The only thing you can assume is
diff --git a/docs/howto/jython.txt b/docs/howto/jython.txt
index 385790e9e6..673c9360bd 100644
--- a/docs/howto/jython.txt
+++ b/docs/howto/jython.txt
@@ -1,5 +1,3 @@
-.. _howto-jython:
-
 ========================
 Running Django on Jython
 ========================
diff --git a/docs/howto/legacy-databases.txt b/docs/howto/legacy-databases.txt
index b2aa7e4ea6..2121871fa2 100644
--- a/docs/howto/legacy-databases.txt
+++ b/docs/howto/legacy-databases.txt
@@ -1,5 +1,3 @@
-.. _howto-legacy-databases:
-
 =========================================
 Integrating Django with a legacy database
 =========================================
@@ -9,7 +7,7 @@ possible to integrate it into legacy databases. Django includes a couple of
 utilities to automate as much of this process as possible.
 
 This document assumes you know the Django basics, as covered in the
-:ref:`tutorial <intro-tutorial01>`.
+:doc:`tutorial </intro/tutorial01>`.
 
 Once you've got Django set up, you'll follow this general process to integrate
 with an existing database.
diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt
index 234454c265..169114ff95 100644
--- a/docs/howto/outputting-csv.txt
+++ b/docs/howto/outputting-csv.txt
@@ -1,5 +1,3 @@
-.. _howto-outputting-csv:
-
 ==========================
 Outputting CSV with Django
 ==========================
@@ -61,7 +59,7 @@ mention:
 Using the template system
 =========================
 
-Alternatively, you can use the :ref:`Django template system <topics-templates>`
+Alternatively, you can use the :doc:`Django template system </topics/templates>`
 to generate CSV. This is lower-level than using the convenient CSV, but the
 solution is presented here for completeness.
 
@@ -113,4 +111,4 @@ Other text-based formats
 Notice that there isn't very much specific to CSV here -- just the specific
 output format. You can use either of these techniques to output any text-based
 format you can dream of. You can also use a similar technique to generate
-arbitrary binary data; see :ref:`howto-outputting-pdf` for an example.
+arbitrary binary data; see :doc:`/howto/outputting-pdf` for an example.
diff --git a/docs/howto/outputting-pdf.txt b/docs/howto/outputting-pdf.txt
index 94acab8311..32e38aebc6 100644
--- a/docs/howto/outputting-pdf.txt
+++ b/docs/howto/outputting-pdf.txt
@@ -1,5 +1,3 @@
-.. _howto-outputting-pdf:
-
 ===========================
 Outputting PDFs with Django
 ===========================
@@ -154,5 +152,5 @@ Other formats
 Notice that there isn't a lot in these examples that's PDF-specific -- just the
 bits using ``reportlab``. You can use a similar technique to generate any
 arbitrary format that you can find a Python library for. Also see
-:ref:`howto-outputting-csv` for another example and some techniques you can use
+:doc:`/howto/outputting-csv` for another example and some techniques you can use
 when generated text-based formats.
diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt
index f93a4e9ba4..209cf38c36 100644
--- a/docs/howto/static-files.txt
+++ b/docs/howto/static-files.txt
@@ -1,5 +1,3 @@
-.. _howto-static-files:
-
 =========================
 How to serve static files
 =========================
@@ -33,7 +31,7 @@ Using this method is **inefficient** and **insecure**. Do not use this in a
 production setting. Use this only for development.
 
 For information on serving static files in an Apache production environment,
-see the :ref:`Django mod_python documentation <serving-media-files>`.
+see the :ref:`Django mod_wsgi documentation <serving-media-files>`.
 
 How to do it
 ============
@@ -42,7 +40,7 @@ Here's the formal definition of the :func:`~django.views.static.serve` view:
 
 .. function:: def serve(request, path, document_root, show_indexes=False)
 
-To use it, just put this in your :ref:`URLconf <topics-http-urls>`::
+To use it, just put this in your :doc:`URLconf </topics/http/urls>`::
 
     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',
             {'document_root': '/path/to/media'}),
@@ -71,7 +69,7 @@ required. For example, if we have a line in ``settings.py`` that says::
 
     STATIC_DOC_ROOT = '/path/to/media'
 
-...we could write the above :ref:`URLconf <topics-http-urls>` entry as::
+...we could write the above :doc:`URLconf </topics/http/urls>` entry as::
 
     from django.conf import settings
     ...