Index: shortcuts.txt
===================================================================
--- shortcuts.txt	(revision 6216)
+++ shortcuts.txt	(working copy)
@@ -6,36 +6,119 @@
 "span" multiple levels of MVC. In other words, these functions/classes
 introduce controlled coupling for convenience's sake.
 
-``render_to_response``
-======================
+The ``render_to_response()`` shortcut
+=====================================
 
-``django.shortcuts.render_to_response`` renders a given template with a given
-context dictionary and returns an ``HttpResponse`` object with that rendered
-text.
+Django provides a shortcut, ``django.shortcuts.render_to_response``, for loading a template, filling
+its context, and returning `an HttpResponse object`_. 
 
-Example::
+**Required arguments:**
 
+    ``template``
+        The full name of a template to use.
+
+**Optional arguments:**
+
+    ``context``
+        A dictionary of values to add to the template
+        context. By default, this is an empty dictionary. If a value in the
+        dictionary is callable, the view will call it just before rendering 
+        the template.
+
+    ``mimetype``
+        The MIME type to use for the resulting document. Defaults
+        to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+**Example:**
+
+The following example renders the template ``myapp/index.html`` with the mimetype ``application/xhtml+xml``::
+
     from django.shortcuts import render_to_response
-    r = render_to_response('myapp/template.html', {'foo': 'bar'})
+    
+    def my_view(request):
+        # View code here
+        return render_to_response("myapp/index.html", {"foo": "bar"}, mimetype="application/xhtml+xml")
 
 This example is equivalent to::
 
     from django.http import HttpResponse
     from django.template import Context, loader
-    t = loader.get_template('myapp/template.html')
-    c = Context({'foo': 'bar'})
-    r = HttpResponse(t.render(c))
+    
+    def my_view(request):
+        # View code here
+        t = loader.get_template('myapp/template.html')
+        c = Context({'foo': 'bar'})
+        r = HttpResponse(t.render(c), mimetype="application/xhtml+xml")
+    
+.. _an HttpResponse object: ../request_response/#httpresponse-objects
 
-``get_object_or_404``
-=====================
+The ``get_object_or_404`` shortcut
+==================================
 
-``django.shortcuts.get_object_or_404`` calls ``get()`` on a given model
+``django.shortcuts.get_object_or_404`` calls `get()`_ on a given model
 manager, but it raises ``django.http.Http404`` instead of the model's
 ``DoesNotExist`` exception.
 
-``get_list_or_404``
-===================
+**Required arguments:**
+    klass
+        A Model, Manager, or Queryset object from which to get the object.
+        
+    kwargs
+        Lookup parameters, which should be in the format described in
+        Field lookups.
+        
+The following example gets the object with the primary key of 1 from ``MyModel``::
 
-``django.shortcuts.get_list_or_404`` returns the result of ``filter()`` on a
+    from django.shortcuts import get_object_or_404
+    
+    def my_view(request):
+        my_object = get_object_or_404(MyModel, pk=1)
+        
+This example is equivalent to::
+
+    from django.core.exceptions import ObjectDoesNotExist
+    from django.http import Http404
+    
+    def my_view(request):
+        try:
+            my_object = MyModels.object.get(pk=1)
+        except ObjectDoesNotExist:
+            raise Http404
+
+Note: Like with get(), an AssertionError will be raised if more than one 
+object is found.
+
+.. _get(): ../db-api/#get-kwargs
+
+The ``get_list_or_404`` shortcut
+================================
+
+``django.shortcuts.get_list_or_404`` returns the result of `filter()`_ on a
 given model manager, raising ``django.http.Http404`` if the resulting list is
 empty.
+
+**Required arguments:**
+    klass
+        A Model, Manager, or Queryset object from which to get the object.
+        
+    kwargs
+        Lookup parameters, which should be in the format described in
+        Field lookups.
+        
+The following example gets all published objects from ``MyModel``::
+
+    from django.shortcuts import get_list_or_404
+
+    def my_view(request):
+        my_objects = get_list_or_404(MyModel, published=True)
+
+This example is equivalent to::
+
+    from django.http import Http404
+
+    def my_view(request):
+        my_objects = MyModels.object.filter(published=True)
+        if not my_objects:
+            raise Http404
+
+.. _filter(): ../db-api/#filter-kwargs