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] 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 5f5f450f..558a80e5 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