newforms-admin: Merged to [5983]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@5984 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/contributing.txt

@@ -286,7 +286,7 @@ Please follow these coding standards when writing code for inclusion in Django:
     * Mark all strings for internationalization; see the `i18n documentation`_
       for details.
 
-    * In docstrings, use "action words," like so::
+    * In docstrings, use "action words" such as::
 
           def foo():
               """

docs/install.txt

@@ -48,8 +48,8 @@ Get your database running
 
 If you plan to use Django's database API functionality, you'll need to
 make sure a database server is running. Django works with PostgreSQL_,
-MySQL_, Oracle_ and SQLite_ (the latter doesn't require a separate server to
-be running).
+MySQL_, Oracle_ and SQLite_ (although SQLite doesn't require a separate server
+to be running).
 
 Additionally, you'll need to make sure your Python database bindings are
 installed.

docs/man/compile-messages.1

@@ -0,0 +1,40 @@
+.TH "compile-messages.py" "1" "August 2007" "Django Project" ""
+.SH "NAME"
+compile-messages.py \- Internationalization utility for the Django
+web framework
+.SH "SYNOPSIS"
+.B compile-messages.py \fR[-l <locale>]
+
+.SH "DESCRIPTION"
+A Django-customised wrapper around gettext's \fBmsgfmt\fR command. Generates
+binary message catalogs (.mo files) from textual translation descriptions (.po
+files).
+.sp
+The script should be invoked after running
+.BI make-messages.py,
+in the same directory from which
+.BI make-messages.py
+was invoked.
+
+.SH "OPTIONS"
+.TP
+.I \-l <locale>
+Compile the message catalogs for a specific locale. If this option is omitted,
+all message catalogs are (re-)compiled.
+
+.SH "SEE ALSO"
+The man page for
+.BI msgfmt
+from the GNU gettext utilities, and the internationalization documentation
+for Django:
+.sp
+.I http://www.djangoproject.com/documentation/i18n/
+
+.SH "AUTHORS/CREDITS"
+Originally developed at World Online in Lawrence, Kansas, USA. Refer to the
+AUTHORS file in the Django distribution for contributors.
+
+.SH "LICENSE"
+New BSD license. For the full license text refer to the LICENSE file in the
+Django distribution.
+

docs/man/daily_cleanup.1

@@ -0,0 +1,34 @@
+.TH "daily_cleanup.py" "1" "August 2007" "Django Project" ""
+.SH "NAME"
+daily_cleanup.py \- Database clean-up for the Django web framework
+.SH "SYNOPSIS"
+.B daily_cleanup.py
+
+.SH "DESCRIPTION"
+Removes stale session data from a Django database. This means, any session data
+which has an expiry date prior to the date the script is run.
+.sp
+The script can be run manually or can be scheduled to run at regular
+intervals as a
+.BI cron
+job.
+
+.SH "ENVIRONMENT"
+.TP
+.I DJANGO_SETTINGS_MODULE
+This environment variable defines the settings module to be read.
+It should be in Python-import form, e.g. "myproject.settings".
+
+.SH "SEE ALSO"
+The sessions documentation:
+.sp
+.I http://www.djangoproject.com/documentation/sessions/
+
+.SH "AUTHORS/CREDITS"
+Originally developed at World Online in Lawrence, Kansas, USA. Refer to the
+AUTHORS file in the Django distribution for contributors.
+
+.SH "LICENSE"
+New BSD license. For the full license text refer to the LICENSE file in the
+Django distribution.
+

docs/man/gather_profile_stats.1

@@ -0,0 +1,26 @@
+.TH "gather_profile_stats.py" "1" "August 2007" "Django Project" ""
+.SH "NAME"
+gather_profile_stats.py \- Performance analysis tool for the Django web
+framework
+.SH "SYNOPSIS"
+.B python gather_profile_stats.py
+.I <path>
+
+.SH "DESCRIPTION"
+This utility script aggregates profiling logs generated using Python's
+hotshot profiler. The sole command-line argument is the full path to the
+directory containing the profiling logfiles.
+
+.SH "SEE ALSO"
+Discussion of profiling Django applications on the Django project's wiki:
+.sp
+.I http://www.djangoproject.com/wiki/ProfilingDjango
+
+.SH "AUTHORS/CREDITS"
+Originally developed at World Online in Lawrence, Kansas, USA. Refer to the
+AUTHORS file in the Django distribution for contributors.
+
+.SH "LICENSE"
+New BSD license. For the full license text refer to the LICENSE file in the
+Django distribution.
+

docs/man/make-messages.1

@@ -0,0 +1,62 @@
+.TH "make-messages.py" "1" "August 2007" "Django Project" ""
+.SH "NAME"
+make-messages.py \- Internationalization utility for the Django
+web framework
+.SH "SYNOPSIS"
+.B make-messages.py\fR [\-a] [\-v] [\-l <locale>] [\-d <domain>]
+
+.SH "DESCRIPTION"
+This script creates or updates one or more message files for a Django app,
+a Django project or the Django framework itself.  It should be run from one
+of three places: the root directory of a Django app; the root directory
+of a Django project; or the root django directory (the one in your PYTHONPATH,
+not the root of a Subversion checkout).
+.sp
+The script will run over the source tree of an application, project or Django
+itself (depending on where it is invoked), pulling out all strings marked for
+translation and creating or updating a standard PO-format message file for the
+specified language. Refer to Django's internationalization documentation for
+details of where this file is created.
+.sp
+The \fI\-a\fR and \fI\-l\fR options are used to control whether message
+catalogs are created for all locales, or just a single one.
+
+.SH "OPTIONS"
+.TP
+.I \-a
+Run make-messages for all locales specified in the Django settings file. Cannot
+be used in conjuntion with \fI\-l\fR.
+.TP
+.I \-d <domain>
+Specifies the translation domain to use. Valid domains are \fIdjango\fR or
+\fIdjangojs\fR, depending on whether you wish to generate translation strings
+for the Python or JavaScript components of your app, your project or the
+framework itself.  The default domain is \fIdjango\fR.
+.TP
+.I \-l <locale>
+Extract messages for a particular locale.
+.TP
+.I \-v
+Run verbosely.
+
+.SH "ENVIRONMENT"
+.TP
+.I DJANGO_SETTINGS_MODULE
+This environment variable defines the settings module to be read.
+It should be in Python-import form, e.g. "myproject.settings".
+
+.SH "SEE ALSO"
+The Django internationalization documentation:
+.sp
+.I http://www.djangoproject.com/documentation/i18n/
+.sp
+The PO file format is documented in the GNU gettext documentation.
+
+.SH "AUTHORS/CREDITS"
+Originally developed at World Online in Lawrence, Kansas, USA. Refer to the
+AUTHORS file in the Django distribution for contributors.
+
+.SH "LICENSE"
+New BSD license. For the full license text refer to the LICENSE file in the
+Django distribution.
+

docs/newforms.txt

@@ -1422,12 +1422,12 @@ keep it simple and assume e-mail validation is contained in a function called
 
     class MultiEmailField(forms.Field):
         def clean(self, value):
+            if not value:
+                raise forms.ValidationError('Enter at least one e-mail address.')
             emails = value.split(',')
             for email in emails:
                 if not is_valid_email(email):
                     raise forms.ValidationError('%s is not a valid e-mail address.' % email)
-            if not emails:
-                raise forms.ValidationError('Enter at least one e-mail address.')
             return emails
 
 Let's alter the ongoing ``ContactForm`` example to demonstrate how you'd use

docs/templates.txt

@@ -937,6 +937,12 @@ such as this::
 
 The template tag will output the string ``/clients/client/123/``.
 
+**New in development version:** If you're using `named URL patterns`_,
+you can refer to the name of the pattern in the ``url`` tag instead of
+using the path to the view.
+
+.. _named URL patterns: ../url_dispatch/#naming-url-patterns
+
 widthratio
 ~~~~~~~~~~
 
@@ -1326,12 +1332,17 @@ urlize
 
 Converts URLs in plain text into clickable links.
 
+Note that if ``urlize`` is applied to text that already contains HTML markup,
+things won't work as expected. Apply this filter only to *plain* text.
+
 urlizetrunc
 ~~~~~~~~~~~
 
 Converts URLs into clickable links, truncating URLs longer than the given
 character limit.
 
+As with urlize_, this filter should only be applied to *plain* text.
+
 **Argument:** Length to truncate URLs to
 
 wordcount

docs/templates_python.txt

@@ -277,7 +277,7 @@ Subclassing Context: RequestContext
 
 Django comes with a special ``Context`` class,
 ``django.template.RequestContext``, that acts slightly differently than
-the normal ``django.template.Context``. The first difference is that takes
+the normal ``django.template.Context``. The first difference is that it takes
 an `HttpRequest object`_ as its first argument. For example::
 
     c = RequestContext(request, {

docs/tutorial04.txt

@@ -193,7 +193,7 @@ Change it like so::
     urlpatterns = patterns('',
         (r'^$', 'django.views.generic.list_detail.object_list', info_dict),
         (r'^(?P<object_id>\d+)/$', 'django.views.generic.list_detail.object_detail', info_dict),
-        (r'^(?P<object_id>\d+)/results/$', 'django.views.generic.list_detail.object_detail', dict(info_dict, template_name='polls/results.html'), 'poll_results'),
+        url(r'^(?P<object_id>\d+)/results/$', 'django.views.generic.list_detail.object_detail', dict(info_dict, template_name='polls/results.html'), 'poll_results'),
         (r'^(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'),
     )
 
@@ -209,11 +209,14 @@ objects" and "display a detail page for a particular type of object."
       from the URL to be called ``"object_id"``, so we've changed ``poll_id`` to
       ``object_id`` for the generic views.
 
-    * We've added a name, ``poll_results``, to the results view so that we have
-      a way to refer to its URL later on (see `naming URL patterns`_ for more on
-      named patterns).
-      
+    * We've added a name, ``poll_results``, to the results view so that we
+      have a way to refer to its URL later on (see the documentation about
+      `naming URL patterns`_ for information). We're also using the `url()`_
+      function from ``django.conf.urls.defaults`` here. It's a good habit to
+      use ``url()`` when you are providing a pattern name like this.
+
 .. _naming URL patterns: ../url_dispatch/#naming-url-patterns
+.. _url(): ../url_dispatch/#url
 
 By default, the ``object_detail`` generic view uses a template called
 ``<app name>/<model name>_detail.html``. In our case, it'll use the template

docs/url_dispatch.txt

@@ -204,8 +204,16 @@ optional extra arguments dictionary. For example::
         ...
     )
 
+This function takes five arguments, most of which are optional::
+
+    url(regex, view, kwargs=None, name=None, prefix='')
+
 See `Naming URL patterns`_ for why the ``name`` parameter is useful.
 
+The ``prefix`` parameter has the same meaning as the first argument to
+``patterns()`` and is only relevant when you're passing a string as the
+``view`` parameter.
+
 handler404
 ----------
 
@@ -512,7 +520,7 @@ view::
 
 This is completely valid, but it leads to problems when you try to do reverse
 URL matching (through the ``permalink()`` decorator or the ``{% url %}``
-template tag). Continuing this example, if you wanted to retrieve the URL for
+`template tag`_). Continuing this example, if you wanted to retrieve the URL for
 the ``archive`` view, Django's reverse URL matcher would get confused, because
 *two* URLpatterns point at that view.
 
@@ -552,14 +560,16 @@ not restricted to valid Python names.
     name, will decrease the chances of collision. We recommend something like
     ``myapp-comment`` instead of ``comment``.
 
+.. _template tag: ../templates/#url
+
 Utility methods
 ===============
 
 reverse()
 ---------
 
-If you need to use something similar to the ``{% url %}`` template tag in your
-code, Django provides the ``django.core.urlresolvers.reverse()``. The
+If you need to use something similar to the ``{% url %}`` `template tag`_ in
+your code, Django provides the ``django.core.urlresolvers.reverse()``. The
 ``reverse()`` function has the following signature::
 
     reverse(viewname, urlconf=None, args=None, kwargs=None)