diff --git a/docs/client-server/howto.rst b/docs/client-server/howto.rst
index 139ccaed8b..25394c05a0 100644
--- a/docs/client-server/howto.rst
+++ b/docs/client-server/howto.rst
@@ -3,20 +3,22 @@ How to use the client-server API
TODO(kegan): Tweak joinalias API keys/path? Event stream historical > live needs
a token (currently doesn't). im/sync responses include outdated event formats
-(room membership change messages).
+(room membership change messages). Room config (specifically: message history,
+public rooms)
+
If you haven't already, get a home server up and running on localhost:8080.
Accounts
========
-Before you can send and receive messages, you must register for an account. If
-you already have an account, you must login into it.
+Before you can send and receive messages, you must **register** for an account.
+If you already have an account, you must **login** into it.
Registration
------------
The aim of registration is to get a user ID and access token which you will need
-when accessing other APIs.
+when accessing other APIs::
curl -XPOST -d '{"user_id":"example", "password":"wordpass"}' "http://localhost:8080/matrix/client/api/v1/register"
@@ -32,7 +34,7 @@ forget the access token.
Login
-----
-The aim of login is to get an access token for your existing user ID.
+The aim of login is to get an access token for your existing user ID::
curl -XGET "http://localhost:8080/matrix/client/api/v1/login"
@@ -55,13 +57,16 @@ you do not know how to login, you can GET /login/fallback which will return a
basic webpage which you can use to login.
-Making rooms and sending messages
-=================================
+Communicating
+=============
+
+In order to communicate with another user, you must **create a room** with that
+user and **send a message** to that room.
Creating a room
---------------
If you want to send a message to someone, you have to be in a room with them. To
-create a room:
+create a room::
curl -XPOST -d '{"room_alias_name":"tutorial"}' "http://localhost:8080/matrix/client/api/v1/rooms?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
@@ -79,20 +84,27 @@ TODO(kegan): How to add/remove aliases from an existing room.
Sending messages
----------------
-You can now send messages to this room:
+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.
+NB: Depending on the room config, users who join the room may be able to see
+message history from before they joined.
-Inviting and joining rooms
-==========================
+Users and rooms
+===============
+
+Each room can be configured to allow or disallow certain rules. In particular,
+these rules may specify if you require an **invitation** from someone already in
+the room in order to **join the room**. In addition, you may also be able to
+join a room **via a room alias** if one was set up.
Inviting a user to a room
-------------------------
-You can directly invite a user to a room like so:
+You can directly invite a user to a room like so::
curl -XPUT -d '{"membership":"invite"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd"
@@ -102,7 +114,7 @@ and allows them to join the room.
Joining a room via an invite
----------------------------
If you receive an invite, you can join the room by changing the membership to
-join:
+join::
curl -XPUT -d '{"membership":"join"}' "http://localhost:8080/matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh:localhost/members/%40myfriend%3Alocalhost/state?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
@@ -112,7 +124,7 @@ state to 'join'.
Joining a room via an alias
---------------------------
Alternatively, if you know the room alias for this room and the room config
-allows it, you can directly join a room via the alias:
+allows it, you can directly join a room via the alias::
curl -XPUT -d '{}' "http://localhost:8080/matrix/client/api/v1/join/%23tutorial%3Alocalhost?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
@@ -122,16 +134,21 @@ 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
+result, it is more common to see a room alias in relation to a public room,
+which do not require invitations.
+
Getting events
==============
An event is some interesting piece of data that a client may be interested in.
It can be a message in a room, a room invite, etc. There are many different ways
-of getting events, depending on what state the client is in.
+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, you can get all your state for all your rooms like so::
curl -XGET "http://localhost:8080/matrix/client/api/v1/im/sync?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK"
@@ -194,7 +211,7 @@ 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:
+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"
@@ -229,7 +246,7 @@ pagination stream parameters to this request:
Getting live state
------------------
Once you know which rooms the client has previously interacted with, you need to
-listen for incoming events. This can be done like so:
+listen for incoming events. This can be done like so::
curl -XGET "http://localhost:8080/matrix/client/api/v1/events?access_token=QG15ZnJpZW5kOmxvY2FsaG9zdA...XKuGdVsovHmwMyDDvK&from=END"
|
