add in version, improve AS API a bit, move eventstream to the right place

specification/00_basis.rst

@@ -7,6 +7,9 @@ Table of Contents
 .. contents:: Table of Contents
 .. sectnum::
 
+Introduction
+============
+
 Matrix is a new set of open APIs for open-federated Instant Messaging and VoIP
 functionality, designed to create and support a new global real-time
 communication ecosystem on the internet. This specification is the ongoing
@@ -78,6 +81,13 @@ instant messages, VoIP call setups, or any other objects that need to be
 reliably and persistently pushed from A to B in an interoperable and federated
 manner.
 
+Version
+=======
+
+The Matrix spec is currently rapidly evolving, and there have been no versioned
+releases as yet.  Versions should be identified by git revision, or failing that
+timestamp.
+
 Basis
 =====
 
@@ -136,8 +146,8 @@ context of a "Room".
 Room structure
 ~~~~~~~~~~~~~~
 
-A room is a conceptual place where users can send and receive events. Rooms can
-be created, joined and left. Events are sent to a room, and all participants in
+A room is a conceptual place where users can send and receive events. 
+Events are sent to a room, and all participants in
 that room with sufficient access will receive the event. Rooms are uniquely
 identified internally via a "Room ID", which look like::
 
@@ -267,7 +277,7 @@ action from the user; either sending a message to a room, or changing presence
 state from a lower to a higher level of availability (thus: changing state from
 ``unavailable`` to ``online`` will count as an action for being active, whereas
 in the other direction will not). This timestamp is presented via a key called
-``last_active_ago``, which gives the relative number of miliseconds since the
+``last_active_ago``, which gives the relative number of milliseconds since the
 message is generated/emitted, that the user was last seen active.
 
 Home servers can also use the user's choice of presence state as a signal for
@@ -439,7 +449,7 @@ authorisation and distribution. These sections must not be encrypted.
 
 State Events
 ++++++++++++
-`State events` are events that update a section of the state of a graph. These
+`State events` are events that update a section of state data for a room. These
 state events hold all the same properties of events, and are part of the event
 graph. The payload of the event is the replacement value for the particular
 section of state being updated.

specification/10_events.rst

@@ -1,28 +1,14 @@
 Events
 ======
 
-Receiving live updates on a client
-----------------------------------
-
-Clients can receive new events by long-polling the home server. This will hold
-open the HTTP connection for a short period of time waiting for new events,
-returning early if an event occurs. This is called the `Event Stream`_. All
-events which are visible to the client will appear in the event stream. When
-the request returns, an ``end`` token is included in the response. This token
-can be used in the next request to continue where the client left off.
+All communication in Matrix is expressed in the form of data objects calle
+Events. These are the fundamental building blocks common to the client-server,
+server-server and application-service APIs, and are described below.
 
 .. TODO-spec
-  How do we filter the event stream?
-  Do we ever return multiple events in a single request?  Don't we get lots of request
-  setup RTT latency if we only do one event per request? Do we ever support streaming
-  requests? Why not websockets?
-
-When the client first logs in, they will need to initially synchronise with
-their home server. This is achieved via the |initialSync|_ API. This API also
-returns an ``end`` token which can be used with the event stream.
+  We *HAVE* to clarify the difference between "state events" and "non-state 
+  events" here (or somewhere like it)
 
-.. TODO-spec
-  We *HAVE* to clarify the difference between "state events" and "non-state events" here (or somewhere like it)
 
 Common event fields
 -------------------
@@ -320,6 +306,13 @@ m.room.message msgtypes
 .. TODO-spec
    How a client should handle unknown message types.
 
+.. TODO-spec
+   We've forgotten m.file...
+
+.. TODO-spec
+   It's really confusing that the m. prefix is used both for event types and
+   for msgtypes.  We should namespace them differently somehow.
+
 Each ``m.room.message`` MUST have a ``msgtype`` key which identifies the type
 of message being sent. Each type has their own required and optional keys, as
 outlined below:
@@ -445,8 +438,8 @@ perform extra roundtrips to query it.
 Voice over IP
 -------------
 Matrix can also be used to set up VoIP calls. This is part of the core
-specification, although is still in a very early stage. Voice (and video) over
-Matrix is based on the WebRTC standards.
+specification, although is at a relatively early stage. Voice (and video) over
+Matrix is built on the WebRTC 1.0 standard.
 
 Call events are sent to a room, like any other event. This means that clients
 must only send call events to rooms with exactly two participants as currently

specification/20_client_server_api.rst

@@ -345,6 +345,29 @@ it should request a login fallback page::
 
 This MUST return an HTML page which can perform the entire login process.
 
+Events
+------
+
+Receiving live updates on a client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Clients can receive new events by long-polling the home server. This will hold
+open the HTTP connection for a short period of time waiting for new events,
+returning early if an event occurs. This is called the `Event Stream`_. All
+events which are visible to the client will appear in the event stream. When
+the request returns, an ``end`` token is included in the response. This token
+can be used in the next request to continue where the client left off.
+
+.. TODO-spec
+  How do we filter the event stream?
+  Do we ever return multiple events in a single request?  Don't we get lots of request
+  setup RTT latency if we only do one event per request? Do we ever support streaming
+  requests? Why not websockets?
+
+When the client first logs in, they will need to initially synchronise with
+their home server. This is achieved via the |initialSync|_ API. This API also
+returns an ``end`` token which can be used with the event stream.
+
 
 Rooms
 -----

specification/30_server_server_api.rst

@@ -298,6 +298,7 @@ destination home server names, and the actual nested content.
 
 Protocol URLs
 -------------
+
 .. WARNING::
   This section may be misleading or inaccurate.
 

specification/40_application_service_api.rst

@@ -1,4 +1,32 @@
 Application Service API
 =======================
 
-The Matrix client-server API and server-server APIs provide the means to implement a consistent self-contained federated messaging fabric.  However, they provide limited means of implementing custom application-layer logic in Matrix services, such as...
+The Matrix client-server API and server-server APIs provide the means to
+implement a consistent self-contained federated messaging fabric. However, they
+provide limited means of implementing custom server-side behaviour in Matrix
+(e.g. gateways, filters, extensible hooks etc).
+
+Defining a standard API to allow such extensible functionality to be implemented
+irrespective of the underlying homeserver implementation is key to enabling
+these services.
+
+Client-Server Services
+----------------------
+
+.. TODO-spec
+  Overview of bots
+
+Passive Application Services
+----------------------------
+
+.. TODO-spec 
+  API that extends the client-server API to allow events to be
+  received with better-than-client permissions.
+
+Active Application Services
+----------------------------
+
+.. TODO-spec
+  API that provides hooks into the server so that you can intercept and
+  manipulate events, and/or insert virtual users & rooms into the server.
+