From c6375ed3d1743eb931e37d12b082c91a2b20d7b4 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 25 Sep 2015 15:09:15 +0100 Subject: [PATCH 01/10] Flesh out feature profiles section Add table detailing the profiles. Add anchors to link through to each module following a well-defined format (rather than the name of the module section). Allow UTF-8 in the spec. --- specification/0-feature_profiles.rst | 35 +++++++++++++++++++ specification/modules/content_repo.rst | 2 ++ .../modules/end_to_end_encryption.rst | 2 ++ specification/modules/instant_messaging.rst | 2 ++ specification/modules/presence.rst | 2 ++ specification/modules/push_overview.rst | 2 ++ specification/modules/receipts.rst | 2 ++ .../modules/typing_notifications.rst | 2 ++ specification/modules/voip_events.rst | 3 ++ templating/build.py | 4 +-- 10 files changed, 54 insertions(+), 2 deletions(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 234e14db..dcf7f642 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -1,3 +1,38 @@ Feature Profiles ================ +Matrix supports many different kinds of clients: from embedded IoT devices to +desktop clients. Not all clients can provide the same feature sets as other +clients e.g. due to lack of physical hardware such as not having a screen. +Clients can fall into one of several profiles and each profile contains a set +of features that the client MUST support. This section details a set of +"feature profiles". Clients are expected to implement a profile in its entirety +in order for it to be classified as that profile. + +Summary +------- + +============================ ===== =========== ======== ========= ===== ===== + Module / Profile Web Embed-Web Mobile Desktop CLI IoT +============================ ===== =========== ======== ========= ===== ===== + `End-to-End Encryption`_ YES YES YES YES + `Instant Messaging`_ YES YES YES YES YES YES + `Presence`_ YES YES YES YES + `Push Notifications`_ YES + `Receipts`_ YES YES YES YES + `Typing Notifications`_ YES YES YES YES + `VoIP`_ YES YES YES + `Content Repository`_ YES YES YES YES +============================ ===== =========== ======== ========= ===== ===== + +*Please see each module for more details on what clients need to implement.* + +.. _End-to-End Encryption: `module:e2e`_ +.. _Instant Messaging: `module:im`_ +.. _Presence: `module:presence`_ +.. _Push Notifications: `module:push`_ +.. _Receipts: `module:receipts`_ +.. _Typing Notifications: `module:typing`_ +.. _VoIP: `module:voip`_ +.. _Content Repository: `module:content`_ + diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index 2c45ced7..c2cf3505 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -1,6 +1,8 @@ Content repository ================== +.. _module:content: + HTTP API -------- diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 02388152..e3a52613 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -1,6 +1,8 @@ End-to-End Encryption ===================== +.. _module:e2e: + .. TODO-doc - Why is this needed. - Overview of process diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 7f582ca4..43a06aa1 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -1,6 +1,8 @@ Instant Messaging ================= +.. _module:im: + Events ------ diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index ddd2adff..cb71107f 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -1,5 +1,7 @@ Presence ======== + +.. _module:presence: Each user has the concept of presence information. This encodes the "availability" of that user, suitable for display on other user's clients. diff --git a/specification/modules/push_overview.rst b/specification/modules/push_overview.rst index 972a8eea..46028283 100644 --- a/specification/modules/push_overview.rst +++ b/specification/modules/push_overview.rst @@ -1,6 +1,8 @@ Push Notifications ================== +.. _module:push: + Overview -------- diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index e2f83eea..9787682f 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -1,6 +1,8 @@ Receipts -------- +.. _module:receipts: + Receipts are used to publish which events in a room the user or their devices have interacted with. For example, which events the user has read. For efficiency this is done as "up to" markers, i.e. marking a particular event diff --git a/specification/modules/typing_notifications.rst b/specification/modules/typing_notifications.rst index 25b714ab..614f6af7 100644 --- a/specification/modules/typing_notifications.rst +++ b/specification/modules/typing_notifications.rst @@ -1,6 +1,8 @@ Typing Notifications -------------------- +.. _module:typing: + Client APIs ~~~~~~~~~~~ diff --git a/specification/modules/voip_events.rst b/specification/modules/voip_events.rst index a5468237..60d61078 100644 --- a/specification/modules/voip_events.rst +++ b/specification/modules/voip_events.rst @@ -1,5 +1,8 @@ Voice over IP ------------- + +.. _module:voip: + Matrix can also be used to set up VoIP calls. This is part of the core 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 diff --git a/templating/build.py b/templating/build.py index 013248f4..6f465607 100755 --- a/templating/build.py +++ b/templating/build.py @@ -122,13 +122,13 @@ def main(input_module, file_stream=None, out_dir=None, verbose=False): # check the input files and substitute in sections where required log("Parsing input template: %s" % file_stream.name) - temp = Template(file_stream.read()) + temp = Template(file_stream.read().decode("utf-8")) log("Creating output for: %s" % file_stream.name) output = create_from_template(temp, sections) with open( os.path.join(out_dir, os.path.basename(file_stream.name)), "w" ) as f: - f.write(output) + f.write(output.encode("utf-8")) log("Output file for: %s" % file_stream.name) check_unaccessed("units", units) From 9fac152d32cea2dff81ed5094bb47dcb793ac640 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 25 Sep 2015 15:26:58 +0100 Subject: [PATCH 02/10] Explain what the clients are and the column reference --- specification/0-feature_profiles.rst | 43 ++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index dcf7f642..4961c216 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -36,3 +36,46 @@ Summary .. _VoIP: `module:voip`_ .. _Content Repository: `module:content`_ +Clients +------- + +Stand-alone web client (``Web``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a web page which heavily uses Matrix for communication. Single-page web +apps would be classified as a stand-alone web client, as would multi-page web +apps which use Matrix on nearly every page. + +Embedded web client (``EmbedWeb``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a Matrix client which is embedded in another website, e.g. using +iframes. These embedded clients are typically for a single purpose +related to the website in question, and are not intended to be fully-fledged +communication apps. + +Mobile client (``Mobile``) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a Matrix client specifically designed for consumption on mobile devices. +This is typically a mobile app but need not be so provided the feature set can +be reached (e.g. if a mobile site could display push notifications it could be +classified as a mobile client). + +Desktop client (``Desktop``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a native application which can run in its own environment outside a +browser. + +Command Line Interface client (``CLI``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a client which is used via a text-based terminal. + +Internet of Things client (``IoT``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a client which is typically running on an embedded device such as a +kettle, fridge or car. + From 510553ee009049616288a262aec3a01705e14429 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 25 Sep 2015 15:29:33 +0100 Subject: [PATCH 03/10] Remove smurf suffixes. Add anchor for feature profiles. --- specification/0-feature_profiles.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 4961c216..ab977162 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -1,6 +1,8 @@ Feature Profiles ================ +.. sect:feature-profiles: + Matrix supports many different kinds of clients: from embedded IoT devices to desktop clients. Not all clients can provide the same feature sets as other clients e.g. due to lack of physical hardware such as not having a screen. @@ -39,42 +41,42 @@ Summary Clients ------- -Stand-alone web client (``Web``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Stand-alone web (``Web``) +~~~~~~~~~~~~~~~~~~~~~~~~~ This is a web page which heavily uses Matrix for communication. Single-page web apps would be classified as a stand-alone web client, as would multi-page web apps which use Matrix on nearly every page. -Embedded web client (``EmbedWeb``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Embedded web (``EmbedWeb``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a Matrix client which is embedded in another website, e.g. using iframes. These embedded clients are typically for a single purpose related to the website in question, and are not intended to be fully-fledged communication apps. -Mobile client (``Mobile``) -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Mobile (``Mobile``) +~~~~~~~~~~~~~~~~~~~ This is a Matrix client specifically designed for consumption on mobile devices. This is typically a mobile app but need not be so provided the feature set can be reached (e.g. if a mobile site could display push notifications it could be classified as a mobile client). -Desktop client (``Desktop``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Desktop (``Desktop``) +~~~~~~~~~~~~~~~~~~~~~ This is a native application which can run in its own environment outside a browser. -Command Line Interface client (``CLI``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Command Line Interface (``CLI``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a client which is used via a text-based terminal. -Internet of Things client (``IoT``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Internet of Things (``IoT``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a client which is typically running on an embedded device such as a kettle, fridge or car. From db8f3c0d5969a6bc731a1e43e23359ea0dd160fe Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 28 Sep 2015 13:11:34 +0100 Subject: [PATCH 04/10] Desktop clients should have a GUI --- specification/0-feature_profiles.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index ab977162..86f8f3d8 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -67,7 +67,7 @@ classified as a mobile client). Desktop (``Desktop``) ~~~~~~~~~~~~~~~~~~~~~ -This is a native application which can run in its own environment outside a +This is a native GUI application which can run in its own environment outside a browser. Command Line Interface (``CLI``) From 82c27884baed11d5dd61bb84786ce05d5c5e47c3 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Tue, 29 Sep 2015 16:29:16 +0100 Subject: [PATCH 05/10] Make E2E optional --- specification/0-feature_profiles.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 86f8f3d8..01997dd5 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -17,7 +17,7 @@ Summary ============================ ===== =========== ======== ========= ===== ===== Module / Profile Web Embed-Web Mobile Desktop CLI IoT ============================ ===== =========== ======== ========= ===== ===== - `End-to-End Encryption`_ YES YES YES YES + `End-to-End Encryption`_ `Instant Messaging`_ YES YES YES YES YES YES `Presence`_ YES YES YES YES `Push Notifications`_ YES From cdf9f011e9eb85cde0840548b1b9a1e5b7885b4e Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Tue, 29 Sep 2015 16:33:34 +0100 Subject: [PATCH 06/10] Add room history visibility as a module. --- specification/0-feature_profiles.rst | 2 ++ specification/modules/history_visibility.rst | 2 ++ 2 files changed, 4 insertions(+) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 01997dd5..59e015e9 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -25,6 +25,7 @@ Summary `Typing Notifications`_ YES YES YES YES `VoIP`_ YES YES YES `Content Repository`_ YES YES YES YES + `History Visibility`_ YES YES YES YES ============================ ===== =========== ======== ========= ===== ===== *Please see each module for more details on what clients need to implement.* @@ -37,6 +38,7 @@ Summary .. _Typing Notifications: `module:typing`_ .. _VoIP: `module:voip`_ .. _Content Repository: `module:content`_ +.. _History Visibility: `module:history-visibility`_ Clients ------- diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst index 01c2e419..371282bd 100644 --- a/specification/modules/history_visibility.rst +++ b/specification/modules/history_visibility.rst @@ -1,6 +1,8 @@ Room History Visibility ----------------------- +.. _module:history-visibility: + Whether a member of a room can see the events that happened in a room from before they joined the room is controlled by the ``history_visibility`` key of the ``m.room.history_visibility`` state event. The valid values for From 0320e8cef32d59ac84131f445937ddc2c05523a3 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 30 Sep 2015 16:41:47 +0100 Subject: [PATCH 07/10] Table tweaks from PR --- specification/0-feature_profiles.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 59e015e9..1d88311b 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -14,19 +14,19 @@ in order for it to be classified as that profile. Summary ------- -============================ ===== =========== ======== ========= ===== ===== - Module / Profile Web Embed-Web Mobile Desktop CLI IoT -============================ ===== =========== ======== ========= ===== ===== - `End-to-End Encryption`_ - `Instant Messaging`_ YES YES YES YES YES YES - `Presence`_ YES YES YES YES - `Push Notifications`_ YES - `Receipts`_ YES YES YES YES - `Typing Notifications`_ YES YES YES YES - `VoIP`_ YES YES YES - `Content Repository`_ YES YES YES YES - `History Visibility`_ YES YES YES YES -============================ ===== =========== ======== ========= ===== ===== +============================ ========== ========== ========== ========== ========== + Module / Profile Web Mobile Desktop CLI Embedded +============================ ========== ========== ========== ========== ========== + `Instant Messaging`_ Required Required Required Required Optional + `Presence`_ Required Required Required Required Optional + `Push Notifications`_ Optional Required Optional Optional Optional + `Receipts`_ Required Required Required Required Optional + `Typing Notifications`_ Required Required Required Required Optional + `VoIP`_ Required Required Required Optional Optional + `Content Repository`_ Required Required Required Optional Optional + `History Visibility`_ Required Required Required Required Optional + `End-to-End Encryption`_ Optional Optional Optional Optional Optional +============================ ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* From be9402b66fbb49c4c23c57e7aec93d1f1efc03f3 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 30 Sep 2015 16:43:09 +0100 Subject: [PATCH 08/10] Move feature profiles section to modules as a sub-section --- specification/0-feature_profiles.rst | 2 +- specification/targets.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 1d88311b..0580c18a 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -25,7 +25,7 @@ Summary `VoIP`_ Required Required Required Optional Optional `Content Repository`_ Required Required Required Optional Optional `History Visibility`_ Required Required Required Required Optional - `End-to-End Encryption`_ Optional Optional Optional Optional Optional + `End-to-End Encryption`_ Optional Optional Optional Optional Optional ============================ ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* diff --git a/specification/targets.yaml b/specification/targets.yaml index 62585c69..d77bf8b5 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -2,11 +2,11 @@ targets: main: # arbitrary name to identify this build target files: # the sort order of files to cat - 0-intro.rst - - { 1: 0-feature_profiles.rst } - 1-client_server_api.rst - { 1: 0-events.rst } - { 1: 0-event_signing.rst } - 2-modules.rst + - { 1: 0-feature_profiles.rst } - { 1: "group:modules" } # reference a group of files - 3-application_service_api.rst - 4-server_server_api.rst From 91b6347f74c4e01ab62b56ee784b735c97d60df0 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 30 Sep 2015 16:48:47 +0100 Subject: [PATCH 09/10] Explain what 'embedded' clients are --- specification/0-feature_profiles.rst | 30 ++++++++++++++++++---------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 0580c18a..5a7e5513 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -50,14 +50,6 @@ This is a web page which heavily uses Matrix for communication. Single-page web apps would be classified as a stand-alone web client, as would multi-page web apps which use Matrix on nearly every page. -Embedded web (``EmbedWeb``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is a Matrix client which is embedded in another website, e.g. using -iframes. These embedded clients are typically for a single purpose -related to the website in question, and are not intended to be fully-fledged -communication apps. - Mobile (``Mobile``) ~~~~~~~~~~~~~~~~~~~ @@ -77,9 +69,25 @@ Command Line Interface (``CLI``) This is a client which is used via a text-based terminal. -Internet of Things (``IoT``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Embedded (``Embedded``) +~~~~~~~~~~~~~~~~~~~~~~~ + +This is a client which is embedded into another application or an embedded +device. + +Application ++++++++++++ + +This is a Matrix client which is embedded in another website, e.g. using +iframes. These embedded clients are typically for a single purpose +related to the website in question, and are not intended to be fully-fledged +communication apps. + +Device +++++++ This is a client which is typically running on an embedded device such as a -kettle, fridge or car. +kettle, fridge or car. These clients tend to perform a few operations and run +in a resource constrained environment. Like embedded applications, they are +not intended to be fully-fledged communication systems. From d092b22848e4ec63aee7c157e2bc2203d6d48d87 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 1 Oct 2015 09:23:08 +0100 Subject: [PATCH 10/10] Rename to 'Managing history visibility' --- specification/0-feature_profiles.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/specification/0-feature_profiles.rst b/specification/0-feature_profiles.rst index 5a7e5513..b9f12b74 100644 --- a/specification/0-feature_profiles.rst +++ b/specification/0-feature_profiles.rst @@ -14,19 +14,19 @@ in order for it to be classified as that profile. Summary ------- -============================ ========== ========== ========== ========== ========== - Module / Profile Web Mobile Desktop CLI Embedded -============================ ========== ========== ========== ========== ========== - `Instant Messaging`_ Required Required Required Required Optional - `Presence`_ Required Required Required Required Optional - `Push Notifications`_ Optional Required Optional Optional Optional - `Receipts`_ Required Required Required Required Optional - `Typing Notifications`_ Required Required Required Required Optional - `VoIP`_ Required Required Required Optional Optional - `Content Repository`_ Required Required Required Optional Optional - `History Visibility`_ Required Required Required Required Optional - `End-to-End Encryption`_ Optional Optional Optional Optional Optional -============================ ========== ========== ========== ========== ========== +===================================== ========== ========== ========== ========== ========== + Module / Profile Web Mobile Desktop CLI Embedded +===================================== ========== ========== ========== ========== ========== + `Instant Messaging`_ Required Required Required Required Optional + `Presence`_ Required Required Required Required Optional + `Push Notifications`_ Optional Required Optional Optional Optional + `Receipts`_ Required Required Required Required Optional + `Typing Notifications`_ Required Required Required Required Optional + `VoIP`_ Required Required Required Optional Optional + `Content Repository`_ Required Required Required Optional Optional + `Managing History Visibility`_ Required Required Required Required Optional + `End-to-End Encryption`_ Optional Optional Optional Optional Optional +===================================== ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* @@ -38,7 +38,7 @@ Summary .. _Typing Notifications: `module:typing`_ .. _VoIP: `module:voip`_ .. _Content Repository: `module:content`_ -.. _History Visibility: `module:history-visibility`_ +.. _Managing History Visibility: `module:history-visibility`_ Clients -------