spec: Added internal links to different sections. Added NOTE and WARNING admonitions and hide away loooong TODO lists behind comments. Smaller ones remain.

1 files changed, 123 insertions, 64 deletions

diff --git a/docs/specification.rst b/docs/specification.rst
index 2b47009187..3c6ed6b1c0 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -278,7 +278,7 @@ which can be set when creating a room:
     The ``name`` value for the ``m.room.name`` state event.
   Description:
     If this is included, an ``m.room.name`` event will be sent into the room to indicate the
-    name of the room. See "Room Events" for more information on ``m.room.name``.
+    name of the room. See `Room Events`_ for more information on ``m.room.name``.
 
 ``topic``
   Type: 
@@ -289,7 +289,7 @@ which can be set when creating a room:
     The ``topic`` value for the ``m.room.topic`` state event.
   Description:
     If this is included, an ``m.room.topic`` event will be sent into the room to indicate the
-    topic for the room. See "Room Events" for more information on ``m.room.topic``.
+    topic for the room. See `Room Events`_ for more information on ``m.room.topic``.
 
 Example::
 
@@ -301,22 +301,30 @@ Example::
   }
 
 - TODO: This creates a room creation event which serves as the root of the PDU graph for this room.
-- TODO: Keys for speccing a room name / room topic / invite these users?
+- TODO: Key for invite these users?
 
 Modifying aliases
 -----------------
-- path to edit aliases
-- format when retrieving list of aliases. NOT complete list.
-- format for adding aliases.
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO kegan
+    - path to edit aliases
+    - format when retrieving list of aliases. NOT complete list.
+    - format for adding aliases.
 
 Permissions
 -----------
-- TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change
-  as people join and leave rooms? What do you do if you get a clash? Examples.
-- TODO: List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
-- TODO: Room config - what is the event and what are the keys/values and explanations for them.
-  Link through to respective sections where necessary. How does this tie in with permissions, e.g.
-  give example of creating a read-only room.
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO kegan
+    - TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change
+      as people join and leave rooms? What do you do if you get a clash? Examples.
+    - TODO: List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
+    - TODO: Room config - what is the event and what are the keys/values and explanations for them.
+      Link through to respective sections where necessary. How does this tie in with permissions, e.g.
+      give example of creating a read-only room.
 
 
 Joining rooms
@@ -345,7 +353,7 @@ by sending the following request to
     "membership": "join"
   }
 
-See the "Room events" section for more information on ``m.room.member``.
+See the `Room events`_ section for more information on ``m.room.member``.
 
 After the user has joined a room, they will receive subsequent events in that room. This room
 will now appear as an entry in the ``/initialSync`` API.
@@ -387,7 +395,7 @@ directly by sending the following request to
     "membership": "invite"
   }
 
-See the "Room events" section for more information on ``m.room.member``.
+See the `Room events`_ section for more information on ``m.room.member``.
 
 - TODO: In what circumstances will this NOT be equivalent to ``/invite``?
 
@@ -408,7 +416,7 @@ directly by sending the following request to
     "membership": "leave"
   }
 
-See the "Room events" section for more information on ``m.room.member``.
+See the `Room events`_ section for more information on ``m.room.member``.
 
 Once a user has left a room, that room will no longer appear on the ``/initialSync``
 API. Be aware that leaving a room is not equivalent to have never been
@@ -506,7 +514,7 @@ In some cases, there may be no need for a ``state_key``, so it can be omitted::
   PUT /rooms/!roomid:domain/state/m.room.bgd.color
   { "color": "red", "hex": "#ff0000" }
 
-See "Room Events" for the ``m.`` event specification.
+See `Room Events`_ for the ``m.`` event specification.
 
 Non-state events
 ----------------
@@ -521,7 +529,7 @@ For example::
   PUT /rooms/!roomid:domain/send/m.custom.example.message/11
   { "text": "Goodbye world!" }
 
-See "Room Events" for the ``m.`` event specification.
+See `Room Events`_ for the ``m.`` event specification.
 
 Syncing rooms
 -------------
@@ -588,7 +596,11 @@ There are several APIs provided to ``GET`` events for a room:
 
 Room Events
 ===========
-- voip events?
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO dave?
+  - voip events?
 
 This specification outlines several standard event types, all of which are
 prefixed with ``m.``
@@ -637,7 +649,7 @@ prefixed with ``m.``
     membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions
     rather than adjusting the state directly as there are a restricted set of valid
     transformations. For example, user A cannot force user B to join a room, and trying
-    to force this state change directly will fail. See the "Rooms" section for how to 
+    to force this state change directly will fail. See the `Rooms`_ section for how to 
     use the membership APIs.
 
 ``m.room.config``
@@ -678,7 +690,7 @@ prefixed with ``m.``
     The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc.
     Whilst not required, the ``body`` key SHOULD be used with every kind of ``msgtype`` as
     a fallback mechanism when a client cannot render the message. For more information on 
-    the types of messages which can be sent, see "m.room.message msgtypes".
+    the types of messages which can be sent, see `m.room.message msgtypes`_.
 
 ``m.room.message.feedback``
   Summary:
@@ -799,6 +811,8 @@ The following keys can be attached to any ``m.room.message``:
 
 Presence
 ========
+.. NOTE::
+  This section is a work in progress.
 
 Each user has the concept of presence information. This encodes the
 "availability" of that user, suitable for display on other user's clients. This
@@ -837,8 +851,9 @@ user was last seen online.
 
 Transmission
 ------------
-- Transmitted as an EDU.
-- Presence lists determine who to send to.
+.. TODO:
+  - Transmitted as an EDU.
+  - Presence lists determine who to send to.
 
 Presence List
 -------------
@@ -863,28 +878,43 @@ presence information in a user list for a room.
 
 Typing notifications
 ====================
-- what is the event type. Are they bundled with other event types? If so, which.
-- what are the valid keys / values. What do they represent. Any gotchas?
-- Timeouts. How do they work, who sets them and how do they expire. Does one
-  have priority over another? Give examples.
+.. NOTE::
+  This section is a work in progress.
 
-TODO : Leo
+.. TODO Leo
+    - what is the event type. Are they bundled with other event types? If so, which.
+    - what are the valid keys / values. What do they represent. Any gotchas?
+    - Timeouts. How do they work, who sets them and how do they expire. Does one
+      have priority over another? Give examples.
 
 Voice over IP
 =============
-- what are the event types.
-- what are the valid keys/values. What do they represent. Any gotchas?
-- In what sequence should the events be sent?
-- How do you accept / decline inbound calls? How do you make outbound calls?
-  Give examples.
-- How does negotiation work? Give examples.
-- How do you hang up?
-- What does call log information look like e.g. duration of call?
-
-TODO : Dave
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO Dave
+    - what are the event types.
+    - what are the valid keys/values. What do they represent. Any gotchas?
+    - In what sequence should the events be sent?
+    - How do you accept / decline inbound calls? How do you make outbound calls?
+      Give examples.
+    - How does negotiation work? Give examples.
+    - How do you hang up?
+    - What does call log information look like e.g. duration of call?
 
 Profiles
 ========
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - Metadata extensibility
+  - Changing profile info generates m.presence events ("presencelike")
+  - keys on m.presence are optional, except presence which is required
+  - m.room.member is populated with the current displayname at that point in time.
+  - That is added by the HS, not you.
+  - Display name changes also generates m.room.member with displayname key f.e. room
+    the user is in.
 
 Internally within Matrix users are referred to by their user ID, which is not a
 human-friendly string. Profiles grant users the ability to see human-readable 
@@ -896,24 +926,20 @@ metadata fields that the user may wish to publish (email address, phone
 numbers, website URLs, etc...). This specification puts no requirements on the 
 display name other than it being a valid unicode string.
 
-- Metadata extensibility
-- Changing profile info generates m.presence events ("presencelike")
-- keys on m.presence are optional, except presence which is required
-- m.room.member is populated with the current displayname at that point in time.
-- That is added by the HS, not you.
-- Display name changes also generates m.room.member with displayname key f.e. room
-  the user is in.
+
 
 Registration and login
 ======================
+.. WARNING::
+  The registration API is likely to change.
+
+- TODO Kegan : Make registration like login (just omit the "user" key on the 
+  initial request?)
 
 Clients must register with a home server in order to use Matrix. After 
 registering, the client will be given an access token which must be used in ALL
 requests to that home server as a query parameter 'access_token'.
 
-- TODO Kegan : Make registration like login (just omit the "user" key on the 
-  initial request?)
-
 If the client has already registered, they need to be able to login to their
 account. The home server may provide many different ways of logging in, such
 as user/password auth, login via a social network (OAuth2), login by confirming 
@@ -1190,9 +1216,11 @@ This MUST return an HTML page which can perform the entire login process.
 
 Identity
 ========
+.. NOTE::
+  This section is a work in progress.
 
-TODO : Dave
-- 3PIDs and identity server, functions
+.. TODO Dave
+  - 3PIDs and identity server, functions
 
 Federation
 ==========
@@ -1233,6 +1261,9 @@ transferred from the origin to the destination home server using an HTTP PUT req
 
 Transactions
 ------------
+.. WARNING::
+  This section may be misleading or inaccurate.
+
 The transfer of EDUs and PDUs between home servers is performed by an exchange
 of Transaction messages, which are encoded as JSON objects, passed over an 
 HTTP PUT request. A Transaction is meaningful only to the pair of home servers that 
@@ -1275,6 +1306,8 @@ mechanism to encourage peers to continue to replicate content.)
 
 PDUs and EDUs
 -------------
+.. WARNING::
+  This section may be misleading or inaccurate.
 
 All PDUs have:
  - An ID
@@ -1345,43 +1378,69 @@ destination home server names, and the actual nested content.
 
 Backfilling
 -----------
-- What it is, when is it used, how is it done
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - What it is, when is it used, how is it done
 
 SRV Records
 -----------
-- Why it is needed
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - Why it is needed
 
 Security
 ========
 - rate limiting
-- crypto (s-s auth)
-- E2E
-- Lawful intercept + Key Escrow
 
-TODO Mark
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - crypto (s-s auth)
+  - E2E
+  - Lawful intercept + Key Escrow
+  TODO Mark
 
 Policy Servers
 ==============
-TODO
+.. NOTE::
+  This section is a work in progress.
 
 Content repository
 ==================
-- path to upload
-- format for thumbnail paths, mention what it is protecting against.
-- content size limit and associated M_ERROR.
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - path to upload
+  - format for thumbnail paths, mention what it is protecting against.
+  - content size limit and associated M_ERROR.
 
 Address book repository
 =======================
-- format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
-- processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
-  contacts), etc.
-- Standard json format for contacts? Piggy back off vcards?
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
+  - processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
+    contacts), etc.
+  - Standard json format for contacts? Piggy back off vcards?
 
 
 Glossary
 ========
-- domain specific words/acronyms with definitions
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO
+  - domain specific words/acronyms with definitions
 
 User ID:
   An opaque ID which identifies an end-user, which consists of some opaque 
   localpart combined with the domain name of their home server. 
+