From 9a9014d54ef51f6ad557c1370150618bdde6eecb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 7 May 2024 17:04:02 +0200 Subject: [PATCH 1/5] Spec markup for mathematical messages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC2191. Signed-off-by: Kévin Commaille --- .../modules/instant_messaging.md | 46 ++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 5f5f450f0..558a80e59 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -73,11 +73,12 @@ the tag. | Tag | Permitted Attributes | |--------|--------------------------------------------------------------------------------------------------------------------------------------------| -| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)) | +| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)), `data-mx-maths` (see [mathematical messages](#mathematical-messages)) | | `a` | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) | | `img` | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (`mxc://`) URI](#matrix-content-mxc-uris)) | | `ol` | `start` | | `code` | `class` (only classes which start with `language-` for syntax highlighting) | +| `div` | `data-mx-maths` (see [mathematical messages](#mathematical-messages)) | Additionally, web clients should ensure that *all* `a` tags get a `rel="noopener"` to prevent the target page from referencing the @@ -385,6 +386,49 @@ An example of a media message with a caption is: Clients MUST render the caption alongside the media and SHOULD prefer its formatted representation. +##### Mathematical messages + +{{% added-in v="1.11" %}} + +Users might want to send mathematical notations in their messages. + +To send mathematical notations clients MUST use the `formatted_body` and +therefore the `org.matrix.custom.html` format, described above. This makes +mathematical notations valid on any `msgtype` which can support this format +appropriately. + +Mathematical notations themselves use the `span` or `div` tags, depending +whether the notation should be presented inline or not. The mathematical +notation is written in [LaTeX](https://www.latex-project.org/) format using the +`data-mx-maths` attribute. + +The contents of the tag should be a fallback representation for clients that +cannot render the LaTeX format. The fallback representation could be, for +example, an image, or an HTML approximation, or the raw LaTeX source. When using +an image as a fallback, the sending client should be aware of issues that may +arise from the receiving client using a different background colour. The `body` +should include a textual representation of the notation. + +An example of a mathematical notation is: + +```json +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "This is an equation: sin(x)=a/b.", + "formatted_body": "This is an equation: + + sin(x)=a/b + " +} +``` + +The LaTeX format is poorly defined and has several extensions, so if a client +encounters syntax that it cannot render, it SHOULD present the fallback +representation instead. Clients SHOULD, however, aim to support, at minimum, the +basic LaTeX2e maths commands and the TeX maths commands, with the possible +exception of commands that could be security risks. + #### Server behaviour Homeservers SHOULD reject `m.room.message` events which don't have a From 0ed05f2a6155a9bc797754d9dfe1910cc590bdc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 7 May 2024 17:08:54 +0200 Subject: [PATCH 2/5] 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/1816.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1816.clarification diff --git a/changelogs/client_server/newsfragments/1816.clarification b/changelogs/client_server/newsfragments/1816.clarification new file mode 100644 index 000000000..e1b97854e --- /dev/null +++ b/changelogs/client_server/newsfragments/1816.clarification @@ -0,0 +1 @@ +Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). \ No newline at end of file From dfbd2e27d3247fad237b8a4d49f8cf0a1585930b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 8 May 2024 18:27:21 +0200 Subject: [PATCH 3/5] Add warning box 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 | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 558a80e59..d396d20e8 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -429,6 +429,15 @@ representation instead. Clients SHOULD, however, aim to support, at minimum, the basic LaTeX2e maths commands and the TeX maths commands, with the possible exception of commands that could be security risks. +{{% boxes/warning %}} +Certain commands, such as [those that can create macros](https://katex.org/docs/supported#macros), +are potentially dangerous. Clients should either decline to process those +commands, or should take care to ensure that they are handled in safe ways (such +as by limiting recursion). In general, LaTeX commands should be filtered by +allowing known-good commands rather than forbidding known-bad commands. Some +LaTeX libraries may have options for doing this. +{{% /boxes/warning %}} + #### Server behaviour Homeservers SHOULD reject `m.room.message` events which don't have a From 601bfd0a394c8824a3be039decd2bb87bff302c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 14 May 2024 12:39:11 +0200 Subject: [PATCH 4/5] Improve warning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../client-server-api/modules/instant_messaging.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index d396d20e8..c19ea9175 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -430,12 +430,17 @@ basic LaTeX2e maths commands and the TeX maths commands, with the possible exception of commands that could be security risks. {{% boxes/warning %}} -Certain commands, such as [those that can create macros](https://katex.org/docs/supported#macros), +In general, LaTeX places a heavy burden on client authors to ensure that it is +processed safely. Certain commands, such as [those that can create macros](https://katex.org/docs/supported#macros), are potentially dangerous. Clients should either decline to process those commands, or should take care to ensure that they are handled in safe ways (such as by limiting recursion). In general, LaTeX commands should be filtered by -allowing known-good commands rather than forbidding known-bad commands. Some -LaTeX libraries may have options for doing this. +allowing known-good commands rather than forbidding known-bad commands. + +Therefore, clients should not render mathematics by calling a LaTeX compiler +without proper sandboxing, as those executables were not written to handle +untrusted input. Some LaTeX rendering libraries are better suited for that by +allowing only a subset of LaTeX and enforcing recursion limits. {{% /boxes/warning %}} #### Server behaviour From 432ce30b082190c79c67cf73e6b345534fcaffdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 27 May 2024 11:31:45 +0200 Subject: [PATCH 5/5] Add links 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 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index c19ea9175..e35a1cdf3 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -426,8 +426,9 @@ An example of a mathematical notation is: The LaTeX format is poorly defined and has several extensions, so if a client encounters syntax that it cannot render, it SHOULD present the fallback representation instead. Clients SHOULD, however, aim to support, at minimum, the -basic LaTeX2e maths commands and the TeX maths commands, with the possible -exception of commands that could be security risks. +basic [LaTeX2e](https://www.latex-project.org/) maths commands and the +[TeX](https://tug.org/) maths commands, with the possible exception of commands +that could be security risks. {{% boxes/warning %}} In general, LaTeX places a heavy burden on client authors to ensure that it is