i18n: merged to [1025] from trunk

git-svn-id: http://code.djangoproject.com/svn/django/branches/i18n@1027 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 48 insertions, 3 deletions

diff --git a/docs/cache.txt b/docs/cache.txt
index f15da2660b..c1b1352bca 100644
--- a/docs/cache.txt
+++ b/docs/cache.txt
@@ -29,7 +29,9 @@ Examples:
     CACHE_BACKEND                   Explanation
     ==============================  ===========================================
     memcached://127.0.0.1:11211/    A memcached backend; the server is running
-                                    on localhost port 11211.
+                                    on localhost port 11211.  You can use
+                                    multiple memcached servers by separating
+                                    them with semicolons.
 
     db://tablename/                 A database backend in a table named
                                     "tablename". This table should be created
@@ -270,6 +272,40 @@ and a list/tuple of header names as its second argument.
 
 .. _`HTTP Vary headers`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
 
+Controlling cache: Using Vary headers
+=====================================
+
+Another problem with caching is the privacy of data, and the question where data can
+be stored in a cascade of caches. A user usually faces two kinds of caches: his own
+browser cache (a private cache) and his providers cache (a public cache). A public cache
+is used by multiple users and controlled by someone else. This poses problems with private
+(in the sense of sensitive) data - you don't want your social security number or your
+banking account numbers stored in some public cache. So web applications need a way
+to tell the caches what data is private and what is public.
+
+Other aspects are the definition how long a page should be cached at max, or wether the
+cache should allways check for newer versions and only deliver the cache content when
+there were no changes (some caches might deliver cached content even if the server page
+changed - just because the cache copy isn't yet expired).
+
+So there are a multitude of options you can control for your pages. This is where the
+Cache-Control header (more infos in `HTTP Cache-Control headers`_) comes in. The usage
+is quite simple::
+
+    @cache_control(private=True, must_revalidate=True, max_age=3600)
+    def my_view(request):
+        ...
+
+This would define the view as private, to be revalidated on every access and cache
+copies will only be stored for 3600 seconds at max.
+
+The caching middleware already set's this header up with a max-age of the CACHE_MIDDLEWARE_SETTINGS
+setting. And the cache_page decorator does the same. The cache_control decorator correctly merges
+different values into one big header, though. But you should take into account that middlewares
+might overwrite some of your headers or set their own defaults if you don't give that header yourself.
+
+.. _`HTTP Cache-Control headers`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
+
 Other optimizations
 ===================
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index fa6d8f10e6..edf94dd17c 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -621,6 +621,14 @@ the relationship should work. All are optional:
                              vertically).
 
     ``limit_choices_to``     See the description under ``ForeignKey`` above.
+
+    ``singular``             The singular name of the field.  Use to name the ``get_*``
+                             methods: in the example above, Django gives the ``Pizza``
+                             objects a ``get_topping_list()`` method, where ``topping``
+                             is the default ``singular`` value derived from the lowercase
+                             version of the class being linked to.  Use the singular
+                             parameter to change this, which is if you want one model to
+                             have multiple ``ManyToMany`` relationships to another model.
     =======================  ============================================================
 
 One-to-one relationships
@@ -750,11 +758,12 @@ Here's a list of all possible ``META`` options. No options are required. Adding
 ``permissions``
     Extra permissions to enter into the permissions table when creating this
     object. Add, delete and change permissions are automatically created for
-    each object. This option specifies extra permissions::
+    each object that has ``admin`` set. This example specifies an extra
+    permission, ``can_deliver_pizzas``::
 
         permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
 
-    This is a list of 2-tuples of
+    This is a list or tuple of 2-tuples in the format
     ``(permission_code, human_readable_permission_name)``.
 
 ``unique_together``