From 12f1ede3ed0207dff7cac8e060313df786e09374 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 14 Nov 2024 10:53:45 +0100 Subject: [PATCH 1/4] Remove reply fallbacks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC2781. Signed-off-by: Kévin Commaille --- .../modules/event_replacements.md | 46 +----- .../modules/instant_messaging.md | 13 +- .../client-server-api/modules/rich_replies.md | 151 ++---------------- 3 files changed, 28 insertions(+), 182 deletions(-) diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 50109d073..6824cedd1 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -362,43 +362,9 @@ property under `m.new_content`. #### Edits of replies -Some particular constraints apply to events which replace a -[reply](#rich-replies). In particular: - - * In contrast to the original reply, there should be no `m.in_reply_to` - property in the the `m.relates_to` object, since it would be redundant (see - [Applying `m.new_content`](#applying-mnew_content) above, which notes that - the original event's `m.relates_to` is preserved), as well as being contrary - to the spirit of the event relationships mechanism which expects only one - "parent" per event. - - * `m.new_content` should **not** contain any [reply - fallback](#fallbacks-for-rich-replies), - since it is assumed that any client which can handle edits can also display - replies natively. However, the `content` of the replacement event should provide - fallback content for clients which support neither rich replies nor edits. - -An example of an edit to a reply is as follows: - -```json -{ - "type": "m.room.message", - // irrelevant fields not shown - "content": { - "body": "> <@alice:example.org> question\n\n* reply", - "msgtype": "m.text", - "format": "org.matrix.custom.html", - "formatted_body": "
In reply to @alice:example.org
question
* reply", - "m.new_content": { - "body": "reply", - "msgtype": "m.text", - "format": "org.matrix.custom.html", - "formatted_body": "reply" - }, - "m.relates_to": { - "rel_type": "m.replace", - "event_id": "$original_reply_event" - } - } -} -``` +{{% boxes/note %}} +{{% changed-in v="1.13" %}} +In previous versions of the specification, events which replace a [reply](#rich-replies) +could include a fallback in the `content`. They are now treated as any other +relation. +{{% /boxes/note %}} diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index de388e9e5..0b11156fb 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -98,14 +98,11 @@ having appropriate closing tags, appropriate attributes (considering the custom ones defined in this specification), and generally valid structure. -A special tag, `mx-reply`, may appear on rich replies (described below) -and should be allowed if, and only if, the tag appears as the very first -tag in the `formatted_body`. The tag cannot be nested and cannot be -located after another tag in the tree. Because the tag contains HTML, an -`mx-reply` is expected to have a partner closing tag and should be -treated similar to a `div`. Clients that support rich replies will end -up stripping the tag and its contents and therefore may wish to exclude -the tag entirely. +{{% boxes/note %}} +{{% changed-in v="1.13" %}} +In previous versions of the specification, [rich replies](#rich-replies) could +use a special tag, `mx-reply`, this is no longer the case. +{{% /boxes/note %}} {{% boxes/note %}} A future iteration of the specification will support more powerful and diff --git a/content/client-server-api/modules/rich_replies.md b/content/client-server-api/modules/rich_replies.md index ef07b6972..e465dd05c 100644 --- a/content/client-server-api/modules/rich_replies.md +++ b/content/client-server-api/modules/rich_replies.md @@ -2,6 +2,7 @@ ### Rich replies {{% changed-in v="1.3" %}} +{{% changed-in v="1.13" %}} Rich replies are a special kind of [relationship](#forming-relationships-between-events) which @@ -18,9 +19,22 @@ Additionally, a rich reply can reference any other event type as of v1.3. Previously, a rich reply could only reference another `m.room.message` event. {{% /boxes/note %}} -When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies) -to allow clients which do not render rich replies to still see something which -appears to be a quoted reply. +{{% boxes/note %}} +{{% changed-in v="1.13" %}} +In previous versions of the specification, rich replies could include a fallback +format in the `body` and `formatted_body` for clients that do not support rich +replies, this is no longer the case. Clients might still want to remove this +fallback before rendering the event. + +To strip the fallback on the `body`, the client should iterate over each +line of the string, removing any lines that start with the fallback +prefix ("> ", including the space, without quotes) and stopping when +a line is encountered without the prefix. This prefix is known as the +"fallback prefix sequence". + +To strip the fallback on the `formatted_body`, the client should remove +the entirety of the `mx-reply` tag. +{{% /boxes/note %}} Though rich replies form a relationship to another event, they do not use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to` @@ -48,137 +62,6 @@ An example reply would be: Note that the `event_id` of the `m.in_reply_to` object has the same requirements as if it were to be under `m.relates_to` directly instead. -#### Fallbacks for rich replies - -Some clients may not have support for rich replies and therefore need a -fallback to use instead. Clients that do not support rich replies should -render the event as if rich replies were not special. - -Clients that do support rich replies SHOULD provide the fallback format on -replies, and MUST strip the fallback before rendering the reply. The -specific fallback text is different for each `msgtype`, however the -general format for the `body` is: - -```text -> <@alice:example.org> This is the first line of the original body -> This is the second line - -This is where the reply goes -``` - -The `formatted_body`, if present and using an associated `format` of -`org.matrix.custom.html`, should use the following template: - -```html - -
- In reply to - @alice:example.org -
- -
- -This is where the reply goes. -``` - -If the related event does not have a `formatted_body`, the event's -`body` should be considered after encoding any HTML special characters. -Note that the `href` in both of the anchors use a [matrix.to -URI](/appendices#matrixto-navigation). - -##### Stripping the fallback - -Clients which support rich replies MUST strip the fallback from the -event before rendering the event. This is because the text provided in -the fallback cannot be trusted to be an accurate representation of the -event. After removing the fallback, clients are recommended to represent -the event referenced by `m.in_reply_to` similar to the fallback's -representation, although clients do have creative freedom for their user -interface. Clients should prefer the `formatted_body` over the `body`, -just like with other `m.room.message` events. - -To strip the fallback on the `body`, the client should iterate over each -line of the string, removing any lines that start with the fallback -prefix ("> ", including the space, without quotes) and stopping when -a line is encountered without the prefix. This prefix is known as the -"fallback prefix sequence". - -To strip the fallback on the `formatted_body`, the client should remove -the entirety of the `mx-reply` tag. - -##### Fallback for `m.text`, `m.notice`, and unrecognised message types - -Using the prefix sequence, the first line of the related event's `body` -should be prefixed with the user's ID, followed by each line being -prefixed with the fallback prefix sequence. For example: - -```text -> <@alice:example.org> This is the first line -> This is the second line - -This is the reply -``` - -The `formatted_body` uses the template defined earlier in this section. - -##### Fallback for `m.emote` - -Similar to the fallback for `m.text`, each line gets prefixed with the -fallback prefix sequence. However an asterisk should be inserted before -the user's ID, like so: - -```text -> * <@alice:example.org> feels like today is going to be a great day - -This is the reply -``` - -The `formatted_body` has a subtle difference for the template where the -asterisk is also inserted ahead of the user's ID: - -```html - -
- In reply to - * @alice:example.org -
- -
- -This is where the reply goes. -``` - -##### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file` - -The related event's `body` would be a file name, which may not be very -descriptive. The related event should additionally not have a `format` -or `formatted_body` in the `content` - if the event does have a `format` -and/or `formatted_body`, those fields should be ignored. Because the -filename alone may not be descriptive, the related event's `body` should -be considered to be `"sent a file."` such that the output looks similar -to the following: - -```text -> <@alice:example.org> sent a file. - -This is the reply -``` -```html - -
- In reply to - @alice:example.org -
- sent a file. -
- -This is where the reply goes. -``` - -For `m.image`, the text should be `"sent an image."`. For `m.video`, the -text should be `"sent a video."`. For `m.audio`, the text should be -`"sent an audio file"`. - #### Mentioning the replied to user In order to notify users of the reply, it may be desirable to include the `sender` From edcba83432425c165de3562e07633a0c9e58cc0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 14 Nov 2024 11:06:51 +0100 Subject: [PATCH 2/4] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1994.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1994.feature diff --git a/changelogs/client_server/newsfragments/1994.feature b/changelogs/client_server/newsfragments/1994.feature new file mode 100644 index 000000000..67c00f225 --- /dev/null +++ b/changelogs/client_server/newsfragments/1994.feature @@ -0,0 +1 @@ +Remove reply fallbacks, as per [MSC2781](https://github.com/matrix-org/matrix-spec-proposals/issues/2781). \ No newline at end of file From a98ec33e619b033a2fdb00e35db42eac4fc7f054 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 14 Nov 2024 11:20:34 +0100 Subject: [PATCH 3/4] Remove rich reply fallback from threads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/modules/threading.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/client-server-api/modules/threading.md b/content/client-server-api/modules/threading.md index f082f389c..5fedbcf8b 100644 --- a/content/client-server-api/modules/threading.md +++ b/content/client-server-api/modules/threading.md @@ -106,10 +106,6 @@ flag to `true`. } ``` -For `m.room.message` events represented this way, no [reply fallback](#fallbacks-for-rich-replies) -is specified. This allows thread-aware clients to discard the `m.in_reply_to` object entirely -when `is_falling_back` is `true`. - {{% boxes/note %}} Clients which are acutely aware of threads (they do not render threads, but are otherwise aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type` From 829867f2a0aab1344e05a4f63b86a7ff250df1b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 14 Nov 2024 16:55:33 +0100 Subject: [PATCH 4/4] Add sentence about stripping tag MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/modules/instant_messaging.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 0b11156fb..5b3124d20 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -101,7 +101,8 @@ structure. {{% boxes/note %}} {{% changed-in v="1.13" %}} In previous versions of the specification, [rich replies](#rich-replies) could -use a special tag, `mx-reply`, this is no longer the case. +use a special tag, `mx-reply`, this is no longer the case. Clients should strip +this tag and its content. {{% /boxes/note %}} {{% boxes/note %}}