move matrix-generic documentation from synapse/docs into new matrix-doc project

specification/spec-additions.rst

@@ -0,0 +1,89 @@
+In C-S API > Registration/Login:
+
+Captcha-based
+~~~~~~~~~~~~~
+:Type: 
+  ``m.login.recaptcha``
+:Description: 
+  Login is supported by responding to a captcha, in this case Google's 
+  Recaptcha.
+
+To respond to this type, reply with::
+
+  {
+    "type": "m.login.recaptcha",
+    "challenge": "<challenge token>",
+    "response": "<user-entered text>"
+  }
+
+The Recaptcha parameters can be obtained in Javascript by calling::
+
+  Recaptcha.get_challenge();
+  Recaptcha.get_response();
+
+The home server MUST respond with either new credentials, the next stage of the
+login process, or a standard error response.
+
+
+
+
+In Events:
+
+Common event fields
+-------------------
+All events MUST have the following fields:
+
+``event_id``
+  Type:
+    String.
+  Description:
+    Represents the globally unique ID for this event.
+
+``type``
+  Type:
+    String.
+  Description:
+    Contains the event type, e.g. ``m.room.message``
+
+``content``
+  Type:
+    JSON Object.
+  Description:
+    Contains the content of the event. When interacting with the REST API, this is the HTTP body.
+
+``room_id``
+  Type:
+    String.
+  Description:
+    Contains the ID of the room associated with this event.
+
+``user_id``
+  Type:
+    String.
+  Description:
+    Contains the fully-qualified ID of the user who *sent* this event.
+
+State events have the additional fields:
+
+``state_key``
+  Type:
+    String.
+  Description:
+    Contains the state key for this state event. If there is no state key for this state event, this
+    will be an empty string. The presence of ``state_key`` makes this event a state event.
+
+``required_power_level``
+  Type:
+    Integer.
+  Description:
+    Contains the minimum power level a user must have before they can update this event.
+
+``prev_content``
+  Type:
+    JSON Object.
+  Description:
+    Optional. Contains the previous ``content`` for this event. If there is no previous content, this
+    key will be missing.
+    
+.. TODO-spec
+  How do "age" and "ts" fit in to all this? Which do we expose?

specification/specification-NOTHAVE.rst

@@ -0,0 +1,30 @@
+Matrix Specification NOTHAVEs
+=============================
+
+This document contains sections of the main specification that have been
+temporarily removed, because they specify intentions or aspirations that have
+in no way yet been implemented. Rather than outright-deleting them, they have
+been moved here so as to stand as an initial version for such time as they
+become extant.
+
+
+Presence
+========
+
+Idle Time
+---------
+As well as the basic ``presence`` field, the presence information can also show
+a sense of an "idle timer". This should be maintained individually by the
+user's clients, and the home server can take the highest reported time as that
+to report. When a user is offline, the home server can still report when the
+user was last seen online.
+
+Device Type
+-----------
+
+Client devices that may limit the user experience somewhat (such as "mobile"
+devices with limited ability to type on a real keyboard or read large amounts of
+text) should report this to the home server, as this is also useful information
+to report as "presence" if the user cannot be expected to provide a good typed
+response to messages.
+