generic-auth: Merged to trunk [4183].

git-svn-id: http://code.djangoproject.com/svn/django/branches/generic-auth@4184 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 90 insertions, 2 deletions

diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index a0377700d7..58c01c4fc0 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -48,6 +48,23 @@ See the `csrf documentation`_.
 
 .. _csrf documentation: http://www.djangoproject.com/documentation/csrf/
 
+formtools
+=========
+
+**New in Django development version**
+
+A set of high-level abstractions for Django forms (django.newforms).
+
+django.contrib.formtools.preview
+--------------------------------
+
+An abstraction of the following workflow:
+
+"Display an HTML form, force a preview, then do something with the submission."
+
+Full documentation for this feature does not yet exist, but you can read the
+code and docstrings in ``django/contrib/formtools/preview.py`` for a start.
+
 humanize
 ========
 
diff --git a/docs/newforms.txt b/docs/newforms.txt
new file mode 100644
index 0000000000..f796477a9e
--- /dev/null
+++ b/docs/newforms.txt
@@ -0,0 +1,71 @@
+====================
+The newforms library
+====================
+
+``django.newforms`` is a new replacement for ``django.forms``, the old Django
+form/manipulator/validation framework. This document explains how to use this
+new form library.
+
+Migration plan
+==============
+
+``django.newforms`` currently is only available in the Django development version
+-- i.e., it's not available in the Django 0.95 release. For the next Django
+release, our plan is to do the following:
+
+    * Move the current ``django.forms`` to ``django.oldforms``. This will allow
+      for an eased migration of form code. You'll just have to change your
+      import statements::
+
+          from django import forms             # old
+          from django import oldforms as forms # new
+
+    * Move the current ``django.newforms`` to ``django.forms``.
+
+    * We will remove ``django.oldforms`` in the release *after* the next Django
+      release -- the release that comes after the release in which we're
+      creating ``django.oldforms``.
+
+With this in mind, we recommend you use the following import statement when
+using ``django.newforms``::
+
+    from django import newforms as forms
+
+This way, your code can refer to the ``forms`` module, and when
+``django.newforms`` is renamed to ``django.forms``, you'll only have to change
+your ``import`` statements.
+
+If you prefer "``import *``" syntax, you can do the following::
+
+    from django.newforms import *
+
+This will import all fields, widgets, form classes and other various utilities
+into your local namespace. Some people find this convenient; others find it
+too messy. The choice is yours.
+
+Overview
+========
+
+As the ``django.forms`` system before it, ``django.newforms`` is intended to
+handle HTML form display, validation and redisplay. It's what you use if you
+want to perform server-side validation for an HTML form.
+
+The library deals with these concepts:
+
+    * **Widget** -- A class that corresponds to an HTML form widget, e.g.
+      ``<input type="text">`` or ``<textarea>``. This handles rendering of the
+      widget as HTML.
+
+    * **Field** -- A class that is responsible for doing validation, e.g.
+      an ``EmailField`` that makes sure its data is a valid e-mail address.
+
+    * **Form** -- A collection of fields that knows how to validate itself and
+      display itself as HTML.
+
+More coming soon
+================
+
+That's all the documentation for now. For more, see the file
+http://code.djangoproject.com/browser/django/trunk/tests/regressiontests/forms/tests.py
+-- the unit tests for ``django.newforms``. This can give you a good idea of
+what's possible.
diff --git a/docs/settings.txt b/docs/settings.txt
index ff1e2eeca2..00672060db 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -830,7 +830,7 @@ Default: ``Django/<version> (http://www.djangoproject.com/)``
 The string to use as the ``User-Agent`` header when checking to see if URLs
 exist (see the ``verify_exists`` option on URLField_).
 
-.. URLField: ../model_api/#urlfield
+.. _URLField: ../model_api/#urlfield
 
 USE_ETAGS
 ---------
diff --git a/docs/testing.txt b/docs/testing.txt
index 68eff07788..a0b8a8a187 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -133,7 +133,7 @@ together, picking the test system to match the type of tests you need to
 write.
 
 For developers new to testing, however, this choice can seem
-confusing, so here are a few key differences to help you decide weather
+confusing, so here are a few key differences to help you decide whether
 doctests or unit tests are right for you.
 
 If you've been using Python for a while, ``doctest`` will probably feel more