Proofing

1 files changed, 20 insertions, 19 deletions

diff --git a/docs/client-server/howto.rst b/docs/client-server/howto.rst
index 328f2c6fcb..de096ab60c 100644
--- a/docs/client-server/howto.rst
+++ b/docs/client-server/howto.rst
@@ -35,9 +35,9 @@ when accessing other APIs::
         "user_id": "@example:localhost"
     }
 
-NB: If a user ID is not specified, one will be randomly generated for you. If
-you do not specify a password, you will be unable to login to the account if you
-forget the access token.
+NB: If a ``user_id`` is not specified, one will be randomly generated for you. 
+If you do not specify a ``password``, you will be unable to login to the account
+if you forget the ``access_token``.
 
 Implementation note: The matrix specification does not enforce how users 
 register with a server. It just specifies the URL path and absolute minimum 
@@ -46,7 +46,7 @@ but other home servers may use different methods.
 
 Login
 -----
-The aim of login is to get an access token for your existing user ID::
+The aim when logging in is to get an access token for your existing user ID::
 
     curl -XGET "http://localhost:8080/matrix/client/api/v1/login"
 
@@ -103,7 +103,7 @@ You can now send messages to this room::
     curl -XPUT -d '{"msgtype":"m.text", "body":"hello"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/messages/%40example%3Alocalhost/msgid1?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
     
 NB: There are no limitations to the types of messages which can be exchanged.
-The only requirement is that ``'msgtype'`` is specified.
+The only requirement is that ``"msgtype"`` is specified.
 
 NB: Depending on the room config, users who join the room may be able to see
 message history from before they joined.
@@ -133,7 +133,7 @@ join::
     curl -XPUT -d '{"membership":"join"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
     
 NB: Only the person invited (``@myfriend:localhost``) can change the membership
-state to ``'join'``.
+state to ``"join"``.
 
 Joining a room via an alias
 ---------------------------
@@ -149,7 +149,7 @@ allows it, you can directly join a room via the alias::
 You will need to use the room ID when sending messages, not the room alias.
 
 NB: If the room is configured to be an invite-only room, you will still require
-the invite in order to join the room even though you know the room alias. As a
+an invite in order to join the room even though you know the room alias. As a
 result, it is more common to see a room alias in relation to a public room, 
 which do not require invitations.
 
@@ -162,7 +162,7 @@ of getting events, depending on what the client already knows.
 Getting all state
 -----------------
 If the client doesn't know any information on the rooms the user is 
-invited/joined on, you can get all your state for all your rooms like so::
+invited/joined on, they can get all the user's state for all rooms::
 
     curl -XGET "http://localhost:8080/matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
     
@@ -222,10 +222,10 @@ invited/joined on, you can get all your state for all your rooms like so::
         }
     ]
     
-This returns all the room IDs of rooms you are invited/joined on, as well as all
-of the messages and feedback for these rooms. This can be a LOT of data. You may
-just want the most recent message for each room. This can be done by applying
-pagination stream parameters to this request::
+This returns all the room IDs of rooms the user is invited/joined on, as well as
+all of the messages and feedback for these rooms. This can be a LOT of data. You
+may just want the most recent message for each room. This can be achieved by 
+applying pagination stream parameters to this request::
 
     curl -XGET "http://localhost:8080/matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK&from=END&to=START&limit=1"
     
@@ -271,13 +271,14 @@ listen for incoming events. This can be done like so::
     }
     
 This will block waiting for an incoming event, timing out after several seconds.
-A client should repeatedly make requests with the ``from`` query parameter with 
-the value of ``end`` (in this case ``215``). This value should be stored so when
-the client reopens your app after a period of inactivity, you can resume from 
-where you got up to in the event stream. If it has been a long period of 
-inactivity, there may be LOTS of events waiting for you. In this case, you may 
-wish to get all state instead and then resume getting live state from a newer 
-end token.
+Even if there are no new events (as in the example above), there will be some
+pagination stream response keys. The client should make subsequent requests 
+using the value of the ``"end"`` key (in this case ``215``) as the ``from`` 
+query parameter. This value should be stored so when the client reopens your app
+after a period of inactivity, you can resume from where you got up to in the 
+event stream. If it has been a long period of inactivity, there may be LOTS of 
+events waiting for the user. In this case, you may wish to get all state instead
+and then resume getting live state from a newer end token.
 
 NB: The timeout can be changed by adding a ``timeout`` query parameter, which is
 in milliseconds. A timeout of 0 will not block.