fix
[django-pagination.git] / doc / usage.rst
index 3e28c66..199e6a3 100644 (file)
@@ -60,6 +60,14 @@ installation, which is covered in :ref:`installation`.)
    
    Note that this replaces ``object_list`` with the list for the current page, so
    you can iterate over the ``object_list`` like you normally would.
+
+   If you are using template ``{% block %}`` tags, the autopaginate tag must
+   exist in the same ``{% block %}`` where you access the paginated
+   ``object_list``.
+
+   In general the full syntax is::
+
+        autopaginate QUERYSET [PAGINATE_BY] [ORPHANS] [as NAME]
    
 
 6. Now you want to display the current page and the available pages, so
@@ -67,7 +75,7 @@ installation, which is covered in :ref:`installation`.)
    
        {% paginate %}
    
-   This does not take any arguments, but does assume that you have already
+   This does not require any arguments, but does assume that you have already
    called autopaginate, so make sure to do so first.
 
 
@@ -77,14 +85,24 @@ a way to navigate between the different pages--all without touching your views.
 Custom pagination templates
 ===========================
 
-In order to override the default pagination template use the extended form of
-the ``paginate`` tag::
+By default the objects will be paginated using a helper template
+"pagination/pagination.html". You can change this with an argument to
+``paginate``.
+
+In general the full syntax is::
+
+        paginate [using "TEMPLATE"]
+
+For example, to paginate posts on a hypothetical blog page you could use
+something like this::
 
     {% autopaginate posts pagesize %}
     {% paginate using "pagination/blog/post.html" %}
 
 The default pagination template is contained in the
-``pagination/pagination.html`` file inside the distribution.
+``pagination/pagination.html`` file inside the distribution. You could extend
+it and only customize the parts you care about. Please inspect the template to
+see the blocks it defines that you could customize.
 
 
 Multiple paginations per page
@@ -150,3 +168,7 @@ behavior of the pagination tags.  Here's an overview:
 ``PAGINATION_DISPLAY_DISABLED_NEXT_LINK``
     If set to ``False``, the next page link will not be displayed if there's no 
     next page. Defaults to False.
+
+``PAGINATION_DISABLE_LINK_FOR_FIRST_PAGE``
+    if set to ``False``, the first page will have ``?page=1`` link suffix in pagination displayed, otherwise is omitted.
+    Defaults to True.