Limit 80; fix RST formatting.

drafts/general_api.rst

@@ -1,7 +1,7 @@
 Instant Messaging
 =================
-This contains the formal proposal for Matrix Client-Server API v2. This API would
+This contains the formal proposal for Matrix Client-Server API v2. This API 
-completely replace v1. It is a general API, not specific to any particular 
+would completely replace v1. It is a general API, not specific to any particular 
 protocol e.g. HTTP. It contains the following APIs:
 
 - Filtering API
@@ -104,25 +104,30 @@ Inputs:
  - Whether you want coalesced ``updates`` events
  - Whether you want coalesced ``relates_to`` events (and the max # to coalesce)
  - limit= param?
- - Which keys to return for events? e.g. no ``origin_server_ts`` if you don't show timestamps
+ - Which keys to return for events? e.g. no ``origin_server_ts`` if you don't 
+   show timestamps
 Outputs:
  - An opaque token which represents the inputs
 Notes:
  - The token may expire, in which case you would need to request another one.
- - The token could be as simple as a concatenation of the requested filters with a delimiter between them.
+ - The token could be as simple as a concatenation of the requested filters with
+   a delimiter between them.
  - Omitting the token on APIs results in ALL THE THINGS coming down.
  - Clients should remember which token they need to use for which API.
- - HTTP note: If the filter API is a separate endpoint, then you could easily allow APIs which use filtering
+ - HTTP note: If the filter API is a separate endpoint, then you could easily 
-   to ALSO specifiy query parameters to tweak the filter.
+   allow APIs which use filtering to ALSO specifiy query parameters to tweak the
+   filter.
 TODO:
- - Do we want to specify negative filters (e.g. don't give me ``event.type.here`` events)
+ - Do we want to specify negative filters (e.g. don't give me 
+   ``event.type.here`` events)
 
 Global ``/initialSync`` API
 ---------------------------
 Inputs:
  - A way of identifying the user (e.g. access token, user ID, etc)
  - Streaming token (optional)
- - Which state event types to return (e.g. ``m.room.name`` / ``m.room.topic`` / ``m.room.aliases``)
+ - Which state event types to return (e.g. ``m.room.name`` / ``m.room.topic`` 
+   / ``m.room.aliases``)
  - Filter to apply
 Outputs:
  - For each room the user is joined:
@@ -131,56 +136,66 @@ Outputs:
     - max of limit= message events
     - room ID
 Notes:
- - If a streaming token is applied, you will get a delta rather than all the rooms.
+ - If a streaming token is applied, you will get a delta rather than all the 
+   rooms.
 What data flows does it address:
  - Home screen: data required on load.
  
 TODO:
- - Will need some form of state event pagination like we have for message events to handle large
+ - Will need some form of state event pagination like we have for message events
-   amounts of state events for a room. Need to think of the consequences of this: you may not get a
+   to handle large amounts of state events for a room. Need to think of the 
-   ``m.room.member`` for someone's message and so cannot display their display name / avatar.
+   consequences of this: you may not get a ``m.room.member`` for someone's 
-   Do we want to provide pagination on an event type basis?
+   message and so cannot display their display name / avatar. Do we want to 
+   provide pagination on an event type basis?
  - Handle paginating initial sync results themselves (e.g. 10 most recent rooms)
- - No need for state events under the 'state' key to have a ``prev_content``. Can also apply some
+ - No need for state events under the 'state' key to have a ``prev_content``. 
-   optimisations depending on the direction of travel when scrolling back.
+   Can also apply some optimisations depending on the direction of travel when 
+   scrolling back.
    
  
 Event Stream API
 ----------------
 Inputs:
  - Position in the stream
- - Filter to apply: which event types, which room IDs, whether to get out-of-order events, which users 
+ - Filter to apply: which event types, which room IDs, whether to get 
-   to get presence/profile updates for
+   out-of-order events, which users to get presence/profile updates for
  - User ID
  - Device ID
 Outputs:
- - 0-N events the client hasn't seen. NB: Deleted state events will be missing a ``content`` key. Deleted
+ - 0-N events the client hasn't seen. NB: Deleted state events will be missing a
-   message events are ``m.room.redaction`` events.
+   ``content`` key. Deleted message events are ``m.room.redaction`` events.
  - New position in the stream.
 State Events Ordering Notes:
- - Home servers may receive state events over federation that are superceded by state events previously 
+ - Home servers may receive state events over federation that are superceded by 
-   sent to the client. The home server *cannot* send these events to the client else they would end up
+   state events previously sent to the client. The home server *cannot* send 
-   erroneously clobbering the superceding state event. 
+   these events to the client else they would end up erroneously clobbering the
- - As a result, the home server reserves the right to omit sending state events which are known to be
+   superceding state event. 
-   superceded already.
+ - As a result, the home server reserves the right to omit sending state events 
- - This may result in missed *state* events. However, the state of the room will always be eventually
+   which are known to be superceded already.
-   consistent.
+ - This may result in missed *state* events. However, the state of the room will
+   always be eventually consistent.
 Message Events Ordering Notes:
- - Home servers may receive message events over federation that happened a long time ago. The client
+ - Home servers may receive message events over federation that happened a long 
-   may or may not be interested in these message events.
+   time ago. The client may or may not be interested in these message events.
- - For clients which do not store scrollback for a room (they discard events after processing them), 
+ - For clients which do not store scrollback for a room (they discard events 
-   this is not a problem as they only care about the recent messages.
+   after processing them), this is not a problem as they only care about the 
- - For clients which do persist scrollback for a room, they need to know about the message event and
+   recent messages.
-   where to insert it so that scrollback remains consistent and doesn't omit messages.
+ - For clients which do persist scrollback for a room, they need to know about 
- - Clients can specify an input parameter stating that they wish to receive these out-of-order events.
+   the message event and where to insert it so that scrollback remains 
- - The event, when it comes down the stream, will indicate which event it comes after.
+   consistent and doesn't omit messages.
+ - Clients can specify an input parameter stating that they wish to receive 
+   these out-of-order events.
+ - The event, when it comes down the stream, will indicate which event it comes 
+   after.
 Rejected events:
- - A home server may find out via federation that it should not have accepted an event (e.g. to send a
+ - A home server may find out via federation that it should not have accepted 
-   message/state event in a room).
+   an event (e.g. to send a message/state event in a room).
- - If this happens, the home server will send a ``m.room.redaction`` for the event in question. This will
+ - If this happens, the home server will send a ``m.room.redaction`` for the 
-   be a local server event (not shared with other servers).
+   event in question. This will be a local server event (not shared with other 
- - If the event was a state event, it will synthesise a new state event to correct the client's room state.
+   servers).
-   This will be a local server event (not shared with other servers).
+ - If the event was a state event, it will synthesise a new state event to 
+   correct the client's room state. This will be a local server event (not 
+   shared with other servers).
  - In practice, clients don't need any extra special handling for this.
 What data flows does it address:
  - Home Screen: Data required when new message arrives for a room
@@ -195,8 +210,8 @@ What data flows does it address:
 Room Creation
 -------------
 Inputs:
-  - Invitee list of user IDs, public/private, state events to set on creation e.g.
+  - Invitee list of user IDs, public/private, state events to set on creation 
-    name of room, alias of room, topic of room
+    e.g. name of room, alias of room, topic of room
 Output:
   - Room ID
 Notes:
@@ -208,30 +223,34 @@ Joining a room
 --------------
 Inputs:
  - Room ID (with list of servers to join from) / room alias / invite event ID
- - Optional filter (which events to return, whether the returned events should come down
+ - Optional filter (which events to return, whether the returned events should 
-   the event stream)
+   come down the event stream)
 Outputs:
- - Room ID, the returned state events from the filter e.g. Room aliases (plural), Name, 
+ - Room ID, the returned state events from the filter e.g. Room aliases 
-   topic, member list (f.e. member: user ID, avatar, presence, display name, power level, 
+   (plural), Name, topic, member list (f.e. member: user ID, avatar, presence, 
-   whether they are typing), enough messages to fill screen (and whether there are more)
+   display name, power level, whether they are typing), enough messages to fill
+   screen (and whether there are more)
 Notes:
- - How do you return room information? In response to the join, or from the event stream?
+ - How do you return room information? In response to the join, or from the 
- - The events returned need to be filterable. Different clients for the same user may want
+   event stream?
-   different information (e.g. the client performing the join may jump to the chat screen and
+ - The events returned need to be filterable. Different clients for the same 
-   therefore want some messages, whereas the client not performing the join just needs to be
+   user may want different information (e.g. the client performing the join may
-   aware of the new room).
+   jump to the chat screen and therefore want some messages, whereas the client
- - As a result, the join response should return events *instead of* to the event stream, depending
+   not performing the join just needs to be aware of the new room).
-   on the client.
+ - As a result, the join response should return events *instead of* to the 
+   event stream, depending on the client.
 Mapping messages to the event stream:
- - Once you join a room, you will start getting message events for it. How do you know when
+ - Once you join a room, you will start getting message events for it. How do 
-   you started getting events for this room? You need to know so you can provide a token when
+   you know when you started getting events for this room? You need to know so 
-   scrolling back. You cannot currently infer this from the join event itself, as individual
+   you can provide a token when scrolling back. You cannot currently infer this
-   events do not have tokens (only chunks do).
+   from the join event itself, as individual events do not have tokens (only 
- - This token can be provided as a separate server-generated event, or an annotation on the join
+   chunks do).
-   event itself.
+ - This token can be provided as a separate server-generated event, or an 
- - We propose that a server-generated event is sent down the event stream to all clients, rather
+   annotation on the join event itself.
-   than annotating the join event. The server-generated event works nicely for Application 
+ - We propose that a server-generated event is sent down the event stream to all
-   Services where an entity subscribes to a room without a join event.
+   clients, rather than annotating the join event. The server-generated event 
+   works nicely for Application Services where an entity subscribes to a room 
+   without a join event.
 What data flows does it address:
  - Home Screen: Joining a room
  
@@ -267,13 +286,13 @@ Outputs:
 
 Action APIs
 -----------
-The following APIs are "action APIs". This is defined to be a request which alters the state of
+The following APIs are "action APIs". This is defined to be a request which 
-a room you are already joined to.
+alters the state of a room you are already joined to.
 
-When you perform an action in a room, you immediately want to display the local echo. The client
+When you perform an action in a room, you immediately want to display the local 
-can receive the response to the action either directly or from the event stream. The order in which
+echo. The client can receive the response to the action either directly or from 
-you receive these responses is undefined. As a result, clients MUST be able to handle all possible
+the event stream. The order in which you receive these responses is undefined. 
-orderings::
+As a result, clients MUST be able to handle all possible orderings::
 
                  1                           2a                          3
  START ----> REQUEST SENT ---> RESPONSE TO REQUEST RECEIVED --------> GOT BOTH
@@ -283,18 +302,23 @@ orderings::
                  
   1: Can display local echo at this point.
   2a: The request has been successfully processed and can be displayed as Sent.
-  2b/3: The request has been successfully processed and the client knows its position in the event stream.
+  2b/3: The request has been successfully processed and the client knows its 
-
+        position in the event stream.
-When a client sends a request, they can include an "action ID" so that they can match up the event in
+
-the event stream to the request which they made. This ID is created by the client, and MUST be a 
+When a client sends a request, they can include an "action ID" so that they can 
-monotonically increasing integer for that client. This ID serves as a transaction ID for idempotency as
+match up the event in the event stream to the request which they made. This ID 
-well as a sequence ID for ordering actions performed in parallel by that client. Events for actions 
+is created by the client, and MUST be a monotonically increasing integer for 
-performed by a client in that client's event stream will include the action ID the client submitted 
+that client. This ID serves as a transaction ID for idempotency as well as a 
-when making the request. The action ID will *not* appear in other client's event streams.
+sequence ID for ordering actions performed in parallel by that client. Events 
-
+for actions performed by a client in that client's event stream will include the
-Action IDs are optional and are only needed by clients that retransmit their requests, or display local
+action ID the client submitted when making the request. The action ID will *not*
-echo, or allow the submission of multiple requests in parallel. An example of a client which may not need
+appear in other client's event streams.
-the use of action IDs includes bots which operate using basic request/responses in a synchronous fashion.
+
+Action IDs are optional and are only needed by clients that retransmit their 
+requests, or display local echo, or allow the submission of multiple requests 
+in parallel. An example of a client which may not need the use of action IDs 
+includes bots which operate using basic request/responses in a synchronous 
+fashion.
  
 Inviting a user
 ~~~~~~~~~~~~~~~
@@ -314,9 +338,10 @@ Inputs:
 Outputs:
  - None.
 Notes:
- - Giving the event ID rather than user ID/room ID combo because mutliple users can invite the
+ - Giving the event ID rather than user ID/room ID combo because mutliple users 
-   same user into the same room.
+   can invite the same user into the same room.
- - Rejecting an invite results in the ``m.room.member`` state event being DELETEd for that user.
+ - Rejecting an invite results in the ``m.room.member`` state event being 
+   DELETEd for that user.
    
 Deleting a state event
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -327,8 +352,8 @@ Inputs:
 Outputs:
  - None.
 Notes:
- - This is represented on the event stream as an event lacking a ``content`` key (for symmetry 
+ - This is represented on the event stream as an event lacking a ``content`` 
-   with ``prev_content``)
+   key (for symmetry with ``prev_content``)
  
 Kicking a user
 ~~~~~~~~~~~~~~
@@ -364,32 +389,37 @@ Outputs:
 What data flows does it address:
  - Chat Screen: Send a Message
 Ordering notes:
- - HTTP: When sending a message with a higher seqnum, it will block the request until it receives 
+ - HTTP: When sending a message with a higher seqnum, it will block the request 
-   earlier seqnums. The block will expire after a timeout and reject the message stating that it 
+   until it receives earlier seqnums. The block will expire after a timeout and
-   was missing a seqnum.
+   reject the message stating that it was missing a seqnum.
 E2E Notes:
- - For signing: You send the original message to the HS and it will return the full event JSON which will
+ - For signing: You send the original message to the HS and it will return the 
-   be sent. This full event is then signed and sent to the HS again to send the message.
+   full event JSON which will be sent. This full event is then signed and sent 
+   to the HS again to send the message.
  
 Sessions
 --------
-A session is a group of requests sent within a short amount of time by the same client. 
+A session is a group of requests sent within a short amount of time by the same 
-Sessions time out after a short amount of time without any requests. Starting
+client. Sessions time out after a short amount of time without any requests. 
-a session is known as going "online". Its purpose is to wrap up the expiry of presence and 
+Starting a session is known as going "online". Its purpose is to wrap up the 
-typing notifications into a clearer scope. A session starts when the client makes any request.
+expiry of presence and typing notifications into a clearer scope. A session 
-A session ends when the client doesn't make a request for a particular amount of time (times out).
+starts when the client makes any request. A session ends when the client doesn't
-A session can also end when explicitly hitting a particular endpoint. This is known as going "offline".
+make a request for a particular amount of time (times out). A session can also 
-
+end when explicitly hitting a particular endpoint. This is known as going 
-When a session starts, a session ID is sent in response to the first request the client makes. This
+"offline".
-session ID should be sent in *all* subsequent requests. If the server expires a session and the client
+
-uses an old session ID, the server should fail the request with the old session ID and send a new 
+When a session starts, a session ID is sent in response to the first request the
-session ID in response for the client to use. If the client receives a new session ID mid-session, 
+client makes. This session ID should be sent in *all* subsequent requests. If 
-it must re-establish its typing status and presence status, as they are linked to the session ID.
+the server expires a session and the client uses an old session ID, the server 
+should fail the request with the old session ID and send a new session ID in 
+response for the client to use. If the client receives a new session ID 
+mid-session, it must re-establish its typing status and presence status, as they
+are linked to the session ID.
 
 Presence
 ~~~~~~~~
-When a session starts, the home server can treat the user as "online". When the session ends, the home
+When a session starts, the home server can treat the user as "online". When the 
-server can treat the user as "offline".
+session ends, the home server can treat the user as "offline".
 
 Inputs:
  - Presence state (online, offline, away, busy, do not disturb, etc)
@@ -401,9 +431,9 @@ Notes:
 
 Typing
 ~~~~~~
-When in a session, a user can send a request stating that they are typing in a room. They are no longer
+When in a session, a user can send a request stating that they are typing in a 
-typing when either the session ends or they explicitly send another request to say they are no longer
+room. They are no longer typing when either the session ends or they explicitly 
-typing.
+send another request to say they are no longer typing.
 
 Inputs:
  - Room ID
@@ -415,84 +445,96 @@ Notes:
  
 Action IDs
 ~~~~~~~~~~
-Action IDs are scoped per session. The first action ID for a session should be 0. For each subsequent
+Action IDs are scoped per session. The first action ID for a session should be 
-action request, the ID should be incremented by 1. It should be reset to 0 when a new session starts.
+0. For each subsequent action request, the ID should be incremented by 1. It 
+should be reset to 0 when a new session starts.
 
-If the client sends an action request with a stale session ID, the home server MUST fail the request
+If the client sends an action request with a stale session ID, the home server 
-and start a new session. The request needs to be failed in order to avoid edge cases with incrementing
+MUST fail the request and start a new session. The request needs to be failed 
-action IDs.
+in order to avoid edge cases with incrementing action IDs.
 
 Updates (Events)
 ----------------
-Events may update other events. This is represented by the ``updates`` key. This is a key which
+Events may update other events. This is represented by the ``updates`` key. This
-contains the event ID for the event it relates to. Events that relate to other events are referred to
+is a key which contains the event ID for the event it relates to. Events that 
-as "Child Events". The event being related to is referred to as "Parent Events". Child events cannot
+relate to other events are referred to as "Child Events". The event being 
-stand alone as a separate entity; they require the parent event in order to make sense.
+related to is referred to as "Parent Events". Child events cannot stand alone as
+a separate entity; they require the parent event in order to make sense.
 
 Bundling
 ~~~~~~~~
-Events that relate to another event should come down inside that event. That is, the top-level event
+Events that relate to another event should come down inside that event. That is,
-should come down with all the child events at the same time. This is called a "bundle" and it is 
+the top-level event should come down with all the child events at the same time.
-represented as an array of events inside the top-level event.There are some issues with this however:
+This is called a "bundle" and it is represented as an array of events inside the
-
+top-level event.There are some issues with this however:
-- Scrollback: Should you be told about child events for which you do not know the parent event?
+
-  Conclusion: No you shouldn't be told about child events. You will receive them when you scroll back
+- Scrollback: Should you be told about child events for which you do not know 
-  to the parent event. 
+  the parent event? Conclusion: No you shouldn't be told about child events. 
-- Pagination of child events: You don't necessarily want to have 1000000s of child events with the
+  You will receive them when you scroll back to the parent event. 
-  parent event. We can't reasonably paginate child events because we require all the child events
+- Pagination of child events: You don't necessarily want to have 1000000s of 
-  in order to display the event correctly. Comments on a message should be done via another technique,
+  child events with the parent event. We can't reasonably paginate child events
-  such as ``relates_to`.
+  because we require all the child events in order to display the event 
-- Do you allow child events to relate to other child events? There is no technical reason why we
+  correctly. Comments on a message should be done via another technique,
-  cannot nest child events, however we can't think of any use cases for it. The behaviour would be
+  such as ``relates_to``.
-  to get the child events recursively from the top-level event. 
+- Do you allow child events to relate to other child events? There is no 
+  technical reason why we cannot nest child events, however we can't think of 
+  any use cases for it. The behaviour would be to get the child events 
+  recursively from the top-level event. 
   
 Main use cases for ``updates``:
- - Call signalling (child events are ICE candidates, answer to the offer, and termination)
+ - Call signalling (child events are ICE candidates, answer to the offer, and 
- - *Local* Delivery/Read receipts : "Local" means they are not shared with other users on the same home
+   termination)
-   server or via federation but *are* shared between clients for the same user; useful for push 
+ - *Local* Delivery/Read receipts : "Local" means they are not shared with other
-   notifications, read count markers, etc. This is done to avoid the ``n^2`` problem for sending 
+   users on the same home server or via federation but *are* shared between 
-   receipts, where the vast majority of traffic tends towards sending more receipts.
+   clients for the same user; useful for push notifications, read count markers,
+   etc. This is done to avoid the ``n^2`` problem for sending receipts, where 
+   the vast majority of traffic tends towards sending more receipts.
  - s/foo/bar/ style message edits
  
-Clients *always* need to know how to apply the deltas because clients may receive the events separately
+Clients *always* need to know how to apply the deltas because clients may 
-down the event stream. Combining event updates server-side does not make client implementation simpler, 
+receive the events separately down the event stream. Combining event updates 
-as the client still needs to know how to combine the events.
+server-side does not make client implementation simpler, as the client still 
+needs to know how to combine the events.
 
 Relates to (Events)
 -------------------
-Events may be in response to other events, e.g. comments. This is represented by the ``relates_to`` 
+Events may be in response to other events, e.g. comments. This is represented 
-key. This differs from the ``updates`` key as they *do not update the event itself*, and are *not required* 
+by the ``relates_to`` key. This differs from the ``updates`` key as they *do 
-in order to display the parent event. Crucially, the child events can be paginated, whereas ``updates`` child events cannot
+not update the event itself*, and are *not required* in order to display the 
-be paginated.
+parent event. Crucially, the child events can be paginated, whereas ``updates`` 
+child events cannot be paginated.
 
 Bundling
 ~~~~~~~~
-Child events can be optionally bundled with the parent event, depending on your display mechanism. The
+Child events can be optionally bundled with the parent event, depending on your 
-number of child events which can be bundled should be limited to prevent events becoming too large. This
+display mechanism. The number of child events which can be bundled should be 
-limit should be set by the client. If the limit is exceeded, then the bundle should also include a pagination
+limited to prevent events becoming too large. This limit should be set by the 
-token so that the client can request more child events.
+client. If the limit is exceeded, then the bundle should also include a 
+pagination token so that the client can request more child events.
 
 Main use cases for ``relates_to``:
  - Comments on a message.
- - Non-local delivery/read receipts : If doing separate receipt events for each message.
+ - Non-local delivery/read receipts : If doing separate receipt events for each 
+   message.
  - Meeting invite responses : Yes/No/Maybe for a meeting.
 
-Like with ``updates``, clients need to know how to apply the deltas because clients may receive the 
+Like with ``updates``, clients need to know how to apply the deltas because 
-events separately down the event stream.
+clients may receive the events separately down the event stream.
 
 TODO:
  - Can a child event reply to multiple parent events? Use case?
- - Should a parent event and its children share a thread ID? Does the originating HS set this ID? Is
+ - Should a parent event and its children share a thread ID? Does the 
-   this thread ID exposed through federation? e.g. can a HS retrieve all events for a given thread ID from
+   originating HS set this ID? Is this thread ID exposed through federation? 
-   another HS?
+   e.g. can a HS retrieve all events for a given thread ID from another HS?
    
 Example using ``updates`` and ``relates_to``
 ---------------------------------------------
 - Room with a single message.
 - 10 comments are added to the message via ``relates_to``.
 - An edit is made to the original message via ``updates``.
-- An initial sync on this room with a limit of 3 comments, would return the message with the update 
+- An initial sync on this room with a limit of 3 comments, would return the 
-  event bundled with it and the most recent 3 comments and a pagination token to request earlier comments
+  message with the update event bundled with it and the most recent 3 comments 
+  and a pagination token to request earlier comments
   
   .. code :: javascript
   
@@ -514,24 +556,28 @@ Example using ``updates`` and ``relates_to``
     
 Events (breaking changes; event version 2)
 ------------------------------------------
-- Prefix the event ``type`` to say if it is a state event, message event or ephemeral event. Needed
+- Prefix the event ``type`` to say if it is a state event, message event or 
-  because you can't tell the different between message events and ephemeral ROOM events (e.g. typing).
+  ephemeral event. Needed because you can't tell the different between message 
-- State keys need additional restrictions in order to increase flexibility on state event permissions.
+  events and ephemeral ROOM events (e.g. typing).
-  State keys prefixed with an ``_`` have no specific restrictions. 0-length state keys are now represented
+- State keys need additional restrictions in order to increase flexibility on 
-  by just a single ``_``. State keys prefixed with ``@`` can be modified only by the named user ID *OR* the
+  state event permissions. State keys prefixed with an ``_`` have no specific 
-  room ops. They can have an optional path suffixed to it. State keys that start with a server name can only
+  restrictions. 0-length state keys are now represented by just a single ``_``.
-  be modified by that server name (e.g. ``some.server.com/some/path`` can only be modified by 
+  State keys prefixed with ``@`` can be modified only by the named user ID *OR* 
-  ``some.server.com``).
+  the room ops. They can have an optional path suffixed to it. State keys that 
-- Do we want to specify what restrictions apply to the state key in the event type? This would allow HSes
+  start with a server name can only be modified by that server name (e.g. 
-  to enforce this, making life easier for clients when dealing with custom event types. E.g. ``_custom.event``
+  ``some.server.com/some/path`` can only be modified by ``some.server.com``).
-  would allow anything in the state key, ``_@custom.event`` would only allow user IDs in the state key, etc.
+- Do we want to specify what restrictions apply to the state key in the event 
+  type? This would allow HSes to enforce this, making life easier for clients 
+  when dealing with custom event types. E.g. ``_custom.event`` would allow 
+  anything in the state key, ``_@custom.event`` would only allow user IDs in 
+  the state key, etc.
 - s/user_id/sender/g given that home servers can send events, not just users.
 
 Capabilities
 ------------
-How does a client know if the server it is using supports a content repository? How does a client know 
+How does a client know if the server it is using supports a content repository? 
-if another client has VoIP support? This section outlines capability publishing for servers,
+How does a client know if another client has VoIP support? This section outlines
-clients and federation.
+capability publishing for servers, clients and federation.
 
 Server
 ~~~~~~
@@ -562,16 +608,19 @@ Client
 ~~~~~~
 - e.g. Whether this client supports VoIP
 
-When a session is started, the client needs to provide a capability set. The server will take the "union"
+When a session is started, the client needs to provide a capability set. The 
-of all the user's connected clients' capability sets and send the hash of the capabilities as part of 
+server will take the "union" of all the user's connected clients' capability 
-presence information (not necesarily as a ``m.presence`` event, but it should act like presence events).
+sets and send the hash of the capabilities as part of presence information 
+(not necesarily as a ``m.presence`` event, but it should act like presence 
+events).
 
-On first signup, the client will attempt to send the hash and be most likely refused by the home server as
+On first signup, the client will attempt to send the hash and be most likely 
-it does not know the full capability set for that hash. The client will then have to upload the full capability
+refused by the home server as it does not know the full capability set for that 
-set to the home server. The client will then be able to send the hash as normal.
+hash. The client will then have to upload the full capability set to the home 
+server. The client will then be able to send the hash as normal.
 
-When a client receives a hash, the client will either recognise the hash or will have to request the capability
+When a client receives a hash, the client will either recognise the hash or 
-set from their home server:
+will have to request the capability set from their home server:
 
 Inputs:
  - Hash
@@ -586,16 +635,18 @@ Federation
 
 VoIP
 ----
-This addresses one-to-one calling with multiple devices. This uses the ``updates`` key to
+This addresses one-to-one calling with multiple devices. This uses the 
-handle signalling.
+``updates`` key to handle signalling.
 
 Event updates
 ~~~~~~~~~~~~~
 - Call is placed by caller. Event generated with offer.
 - 1-N callees may pick up or reject this offer.
 - Callees update the event (with sdp answer if they are accepting the call)
-- Caller acknowledges *one* of the callees (either one which picked up or rejected) by updating the event.
+- Caller acknowledges *one* of the callees (either one which picked up or 
-- Callees who weren't chosen then give up (Answered elsewhere, Rejected elsewhere, etc)
+  rejected) by updating the event.
+- Callees who weren't chosen then give up (Answered elsewhere, Rejected 
+  elsewhere, etc)
 - Update with ICE candidates as they appear.
 - ... in call ...
 - Send hangup update when hanging up.