[1.0.X] Fixed a whole bunch of small docs typos, errors, and ommissio…

…ns. Backport of the parts of r10371 that apply to the 1.0 docs.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@10372 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/utils/html.py

@@ -28,7 +28,9 @@
 del x # Temporary variable
 
 def escape(html):
-    """Returns the given HTML with ampersands, quotes and carets encoded."""
+    """
+    Returns the given HTML with ampersands, quotes and angle brackets encoded.
+    """
     return mark_safe(force_unicode(html).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))
 escape = allow_lazy(escape, unicode)
 

docs/_static/djangodocs.css

@@ -103,9 +103,9 @@ dt .literal, table .literal { background:none; }
 .note, .admonition { padding:.8em 1em .8em; margin: 1em 0; border:1px solid #94da3a; }
 .admonition-title { font-weight:bold; margin-top:0 !important; margin-bottom:0 !important;}
 .admonition .last { margin-bottom:0 !important; }
-.note, .admonition { padding-left:65px; background:url(docicons-note.gif) .8em .8em no-repeat;}
-div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.gif) .8em .8em no-repeat;}
-div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.gif) .8em .8em no-repeat;}
+.note, .admonition { padding-left:65px; background:url(docicons-note.png) .8em .8em no-repeat;}
+div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.png) .8em .8em no-repeat;}
+div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.png) .8em .8em no-repeat;}
 
 /*** versoinadded/changes ***/
 div.versionadded, div.versionchanged {  }

docs/howto/custom-file-storage.txt

@@ -63,7 +63,11 @@ 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. No return value is expected.
+``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
+instead).
 
 ``get_valid_name(name)``
 ------------------------

docs/howto/deployment/modpython.txt

@@ -17,14 +17,22 @@ performance gains over other server arrangements.
 Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
 `prefork MPM`_, as opposed to the `worker MPM`_.
 
-You may also be interested in :ref:`How to use Django with FastCGI, SCGI, or
-AJP <howto-deployment-fastcgi>`.
+.. seealso::
+
+    * Apache is a big, complex animal, and this document only scratches the
+      surface of what Apache can do. If you need more advanced information about
+      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>`.
 
 .. _Apache: http://httpd.apache.org/
 .. _mod_python: http://www.modpython.org/
 .. _mod_perl: http://perl.apache.org/
 .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html
 .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html
+.. _apache's own official documentation: http://httpd.apache.org/docs/
 
 Basic configuration
 ===================
@@ -52,15 +60,15 @@ Django mod_python handler." It passes the value of :ref:`DJANGO_SETTINGS_MODULE
 .. versionadded:: 1.0
     The ``PythonOption django.root ...`` is new in this version.
 
-Because mod_python does not know we are
-serving this site from underneath the ``/mysite/`` prefix, this value needs to
-be passed through to the mod_python handler in Django, via the ``PythonOption
-django.root ...`` line. The value set on that line (the last item) should
-match the string given in the ``<Location ...>`` directive. The effect of this
-is that Django will automatically strip the ``/mysite`` string from the front
-of any URLs before matching them against your URLconf patterns. If you later
-move your site to live under ``/mysite2``, you will not have to change anything
-except the ``django.root`` option in the config file.
+Because mod_python does not know we are serving this site from underneath the
+``/mysite/`` prefix, this value needs to be passed through to the mod_python
+handler in Django, via the ``PythonOption django.root ...`` line. The value set
+on that line (the last item) should match the string given in the ``<Location
+...>`` directive. The effect of this is that Django will automatically strip the
+``/mysite`` string from the front of any URLs before matching them against your
+URLconf patterns. If you later move your site to live under ``/mysite2``, you
+will not have to change anything except the ``django.root`` option in the config
+file.
 
 When using ``django.root`` you should make sure that what's left, after the
 prefix has been removed, begins with a slash. Your URLconf patterns that are
@@ -97,6 +105,10 @@ setting the Python path for interactive usage. Whenever you try to import
 something, Python will run through all the directories in ``sys.path`` in turn,
 from first to last, and try to import from each directory until one succeeds.
 
+Make sure that your Python source files' permissions are set such that the
+Apache user (usually named ``apache`` or ``httpd`` on most systems) will have
+read access to the files.
+
 An example might make this clearer. Suppose you have some applications under
 ``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and
 so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have

docs/howto/initial-data.txt

@@ -47,7 +47,7 @@ look like in JSON:
           "first_name": "Paul",
           "last_name": "McCartney"
         }
-      },
+      }
     ]
 
 And here's that same fixture as YAML:

docs/howto/static-files.txt

@@ -10,9 +10,9 @@ How to serve static files
 Django itself doesn't serve static (media) files, such as images, style sheets,
 or video. It leaves that job to whichever Web server you choose.
 
-The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and Cherokee_,
-are much more fine-tuned at serving static files than a Web application
-framework.
+The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and
+Cherokee_, are much more fine-tuned at serving static files than a Web
+application framework.
 
 With that said, Django does support static files **during development**. You can
 use the :func:`django.views.static.serve` view to serve media files.
@@ -21,6 +21,11 @@ use the :func:`django.views.static.serve` view to serve media files.
 .. _lighttpd: http://www.lighttpd.net/
 .. _Cherokee: http://www.cherokee-project.com/
 
+.. seealso::
+
+    If you just need to serve the admin media from a nonstandard location, see
+    the :djadminopt:`--adminmedia` parameter to :djadmin:`runserver`.
+
 The big, fat disclaimer
 =======================
 

docs/intro/tutorial01.txt

@@ -134,18 +134,27 @@ It worked!
 .. admonition:: Changing the port
 
     By default, the :djadmin:`runserver` command starts the development server
-    on port 8000. If you want to change the server's port, pass it as a
-    command-line argument. For instance, this command starts the server on port
-    8080:
+    on the internal IP at port 8000. 
+
+    If you want to change the server's port, pass
+    it as a command-line argument. For instance, this command starts the server
+    on port 8080:
 
     .. code-block:: bash
 
         python manage.py runserver 8080
+
+    If you want to change the server's IP, pass it along with the port. So to
+    listen on all public IPs (useful if you want to show off your work on other
+    computers), use:
+
+    .. code-block:: bash
+
+        python manage.py runserver 0.0.0.0:8000
 
     Full docs for the development server can be found in the
     :djadmin:`runserver` reference.
 
-
 Database setup
 --------------
 

docs/intro/tutorial03.txt

@@ -302,6 +302,13 @@ for a given poll. Here's the view::
 The new concept here: The view raises the :exc:`~django.http.Http404` exception
 if a poll with the requested ID doesn't exist.
 
+We'll discuss what you could put in that ``polls/detail.html`` template a bit
+later, but if you'd like to quickly get the above example working, just::
+
+    {{ poll }}
+
+will get you started for now.
+
 A shortcut: get_object_or_404()
 -------------------------------
 
@@ -357,6 +364,10 @@ in ``django/conf/urls/defaults.py``, ``handler404`` is set to
 
 Three more things to note about 404 views:
 
+    * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
+      404 view will never be used (and thus the ``404.html`` template will never
+      be rendered) because the traceback will be displayed instead.
+
     * The 404 view is also called if Django doesn't find a match after checking
       every regular expression in the URLconf.
 
@@ -365,8 +376,9 @@ Three more things to note about 404 views:
       template in the root of your template directory. The default 404 view will
       use that template for all 404 errors.
 
-    * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
-      404 view will never be used, and the traceback will be displayed instead.
+    * If :setting:`DEBUG` is set to ``False`` (in your settings module) and if
+      you didn't create a ``404.html`` file, an ``Http500`` is raised instead.
+      So remember to create a ``404.html``.
 
 Write a 500 (server error) view
 ===============================

docs/intro/tutorial04.txt

@@ -20,7 +20,7 @@ tutorial, so that the template contains an HTML ``<form>`` element:
 
     {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
 
-    <form action="/polls/{{ poll.id }}/vote/" method="post">
+    <form action="vote/" method="post">
     {% for choice in poll.choice_set.all %}
         <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />
         <label for="choice{{ forloop.counter }}">{{ choice.choice }}</label><br />
@@ -36,12 +36,12 @@ A quick rundown:
       selects one of the radio buttons and submits the form, it'll send the
       POST data ``choice=3``. This is HTML Forms 101.
 
-    * We set the form's ``action`` to ``/polls/{{ poll.id }}/vote/``, and we
-      set ``method="post"``. Using ``method="post"`` (as opposed to
-      ``method="get"``) is very important, because the act of submitting this
-      form will alter data server-side. Whenever you create a form that alters
-      data server-side, use ``method="post"``. This tip isn't specific to
-      Django; it's just good Web development practice.
+    * We set the form's ``action`` to ``vote/``, and we set ``method="post"``.
+      Using ``method="post"`` (as opposed to ``method="get"``) is very
+      important, because the act of submitting this form will alter data
+      server-side. Whenever you create a form that alters data server-side, use
+      ``method="post"``. This tip isn't specific to Django; it's just good Web
+      development practice.
 
     * ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone
       through its loop
@@ -170,7 +170,17 @@ to write Python code to write an app.
 
 Let's convert our poll app to use the generic views system, so we can delete a
 bunch of our own code. We'll just have to take a few steps to make the
-conversion.
+conversion. We will:
+
+    1. Convert the URLconf.
+
+    2. Rename a few templates.
+
+    3. Delete some the old, now unneeded views.
+
+    4. Fix up URL handling for the new views.
+
+Read on for details.
 
 .. admonition:: Why the code-shuffle?
 

docs/misc/distributions.txt

@@ -4,7 +4,7 @@
 Third-party distributions of Django
 ===================================
 
-Several third-party distributors are now providing versions of Django integrated
+Many third-party distributors are now providing versions of Django integrated
 with their package-management systems. These can make installation and upgrading
 much easier for users of Django since the integration includes the ability to
 automatically install dependencies (like database adapters) that Django
@@ -15,81 +15,14 @@ if you want to use the development version of Django you'll need to follow the
 instructions for :ref:`installing the development version
 <installing-development-version>` from our Subversion repository.
 
-FreeBSD
-=======
+If you're using Linux or a Unix installation, such as OpenSolaris,
+check with your distributor to see if they already package Django. If
+you're using a Linux distro and don't know how to find out if a package
+is available, then now is a good time to learn.  The Django Wiki contains
+a list of `Third Party Distributions`_ to help you out.
 
-The `FreeBSD`_ ports system offers both Django 0.96 (`py-django`_) and a more
-recent, but not current, version based on Django's trunk (`py-django-devel`_).
-These are installed in the normal FreeBSD way; for Django 0.96, for example, type:
-``cd /usr/ports/www/py-django && sudo make install clean``.
+.. _`Third Party Distributions`: http://code.djangoproject.com/wiki/Distributions
 
-.. _FreeBSD: http://www.freebsd.org/
-.. _py-django: http://www.freebsd.org/cgi/cvsweb.cgi/ports/www/py-django/
-.. _py-django-devel: http://www.freebsd.org/cgi/cvsweb.cgi/ports/www/py-django-devel/
-
-Linux distributions
-===================
-
-Debian
-------
-
-A `packaged version of Django`_ is available for `Debian GNU/Linux`_. Version
-0.95.1 is available in the "stable" repository; Version 0.96 is available in
-the "testing" and "unstable" repositories. Regardless of your chosen repository,
-you can install Django by typing ``apt-get install python-django``.
-
-When you install this package, ``apt`` will recommend installing a database
-adapter; you should select and install the adapter for whichever database you
-plan to use with Django.
-
-.. _Debian GNU/Linux: http://www.debian.org/
-.. _packaged version of Django: http://packages.debian.org/stable/python/python-django
-
-Fedora
-------
-
-A Django package is available for `Fedora Linux`_, in the "Fedora Extras"
-repository. The `current Fedora package`_ is based on Django 0.96, and can be
-installed by typing ``yum install Django``. The previous link is for the i386
-binary. Users of other architectures should be able to use that as a starting
-point to find their preferred version.
-
-.. _Fedora Linux: http://fedora.redhat.com/
-.. _current Fedora package: http://download.fedora.redhat.com/pub/fedora/linux/extras/6/i386/repoview/Django.html
-
-Gentoo
-------
-
-A Django package is available for `Gentoo Linux`_, and is based on Django 0.96.1.
-The `current Gentoo package`_ can be installed by typing ``emerge django``.
-
-.. _Gentoo Linux: http://www.gentoo.org/
-.. _current Gentoo package: http://packages.gentoo.org/package/django
-
-Ubuntu
-------
-
-The Debian ``python-django`` package is also available for `Ubuntu Linux`_, in
-the "universe" repository for Ubuntu 7.10 ("Gutsy Gibbon"). The `current Ubuntu
-package`_ is based on Django 0.96.1 and can be installed in the same fashion as
-for Debian.
-
-.. _Ubuntu Linux: http://www.ubuntu.com/
-.. _current Ubuntu package: http://packages.ubuntu.com/gutsy/python/python-django
-
-
-Mac OS X
-========
-
-MacPorts
---------
-
-Django 0.96 can be installed via the `MacPorts`_ system. If you're using Python 2.4,
-type ``sudo port install py-django-devel``. For Python 2.5, type ``sudo port
-install py25-django-devel``. MacPorts can also be used to install a database,
-and the Python interface to your chosen database.
-
-.. _MacPorts: http://www.macports.org/
 
 For distributors
 ================

docs/obsolete/admin-css.txt

@@ -29,7 +29,7 @@ group in a box and applies certain styles to the elements within. An ``h2``
 within a ``div.module`` will align to the top of the ``div`` as a header for the
 whole group.
 
-.. image:: _images/module.gif
+.. image:: _images/module.png
    :alt: Example use of module class on admin homepage
 
 Column Types
@@ -134,7 +134,7 @@ Example from a changelist page:
       <li><a href="/stories/add/" class="addlink">Add redirect</a></li>
     </ul>
 
-.. image:: _images/objecttools_01.gif
+.. image:: _images/objecttools_01.png
    :alt: Object tools on a changelist page
 
 and from a form page:
@@ -146,7 +146,7 @@ and from a form page:
      <li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
     </ul>
 
-.. image:: _images/objecttools_02.gif
+.. image:: _images/objecttools_02.png
    :alt: Object tools on a form page
 
 Form Styles
@@ -176,7 +176,7 @@ Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
 with class ``form-row``. If the field in the row is required, a class of
 ``required`` should also be added to the ``div.form-row``.
 
-.. image:: _images/formrow.gif
+.. image:: _images/formrow.png
    :alt: Example use of form-row class
 
 Labels

docs/ref/contrib/admin.txt

@@ -38,6 +38,11 @@ There are five steps in activating the Django admin site:
        ``ModelAdmin`` classes.
 
     5. Hook the ``AdminSite`` instance into your URLconf.
+
+.. seealso::
+
+    For information about serving the media files (images, JavaScript, and CSS)
+    associated with the admin in production, see :ref:`serving-media-files`.
 
 ``ModelAdmin`` objects
 ======================