Add `dir` parameter to pagination. Remove path references

This section needs a lot of work to not lie.

specification/1-client_server_api.rst

@@ -348,11 +348,13 @@ Pagination
 
 Querying large datasets in Matrix always uses the same pagination API pattern to
 to give clients a consistent way of selecting subsets of a potentially changing
-dataset. Requests pass in ``from``, ``to`` and ``limit`` parameters which describe
+dataset. Requests pass in ``from``, ``to``, ``dir`` and ``limit`` parameters
-where to read from the stream. ``from`` and ``to`` are opaque textual 'stream
+which describe where to read from the stream. ``from`` and ``to`` are opaque
-tokens' which describe positions in the dataset. The response returns new
+textual 'stream tokens' which describe the current position in the dataset.
-``start`` and ``end`` stream token values which can then be passed to subsequent
+The ``dir`` parameter is an enum representing the direction of events to return:
-requests to continue pagination.
+either ``f`` orwards or ``b`` ackwards. The response returns new ``start`` and
+``end`` stream token values which can then be passed to subsequent requests to
+continue pagination.
 
 Pagination Request Query Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -367,24 +369,26 @@ Query parameters:
   limit:
     integer - An integer representing the maximum number of items to 
     return.
+  dir:
+    f|b - The direction to return events in. Typically this is ``b`` to paginate
+    backwards in time.
 
 'START' and 'END' are placeholder values used in these examples to describe the
 start and end of the dataset respectively.
 
-Unless specified, the default pagination parameters are from=START, to=END, 
+Unless specified, the default pagination parameters are ``from=START``,
-without a limit set. This allows you to hit an API like
+``to=END``, without a limit set.
-/events without any query parameters to get everything.
 
-For example, the event stream has events E1 -> E15. The client wants the last 5 
+For example, if an endpoint had events E1 -> E15. The client wants the last 5 
 events and doesn't know any previous events::
 
     S                                                    E
     |-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-|
     |                               |                    |
     |                          _____|                    |
-    |__________________       |       ___________________|
+    |__________________       |           _______________|
-                       |      |      |
+                       |      |           |
-     GET /events?to=START&limit=5&from=END
+     GET /somepath?to=START&limit=5&from=END
      Returns:
        E15,E14,E13,E12,E11
 
@@ -401,7 +405,7 @@ now show page 3 (rooms R11 -> 15)::
                         Currently            |
                         viewing              |
                                              |
-                             GET /rooms/list?from=9&to=END&limit=5
+                             GET /roomslist?from=9&to=END&limit=5
                              Returns: R11,R12,R13,R14,R15
                          
 Note that tokens are treated in an *exclusive*, not inclusive, manner. The end