Fix typesetting of symbols in Olm/Megolm spec (#2421)

* properly typeset symbols in Olm/Megolm message format tables

Signed-off-by: Johanna Stuber <johannas@element.io>

* use \mathit in Olm spec analogously to Megolm spec

Signed-off-by: Johanna Stuber <johannas@element.io>

* add newsfragment

Signed-off-by: Johanna Stuber <johannas@element.io>

* fix typo

Signed-off-by: Johanna Stuber <johannas@element.io>

---------

Signed-off-by: Johanna Stuber <johannas@element.io>

changelogs/client_server/newsfragments/2407.clarification

@@ -0,0 +1 @@
+Add further normative language in mutual rooms server behaviour.

changelogs/olm_megolm/newsfragments/2421.clarification

@@ -0,0 +1 @@
+Fix typesetting of some symbols in the Olm/Megolm spec.

content/client-server-api/modules/mutual_rooms.md

@@ -6,9 +6,9 @@
 
 #### Server behaviour
 
-The server may decide that the response to this endpoint is too large, and only return a
+The server MAY decide that the response to this endpoint is too large, and only return a
-subset of the results. In this case, the server should populate the optional field `next_batch`
+subset of the results. In this case, the server populates the optional field `next_batch`
-with an [opaque identifier](/appendices/#opaque-identifiers). The client may then supply
+with an [opaque identifier](/appendices/#opaque-identifiers). The client can then supply
 the identifier as the `from` query parameter in a subsequent request, along with the original
 `user_id`, to fetch the next batch of responses. This will continue until the server no longer
 inserts `next_batch`, meaning there are no further results.

content/olm-megolm/megolm.md

@@ -257,8 +257,8 @@ consists of the following key-value pairs:
 
 **Name**|**Tag**|**Type**|**Meaning**
 :-----:|:-----:|:-----:|:-----:
-Message-Index|0x08|Integer|The index of the ratchet, i
+Message-Index|0x08|Integer|The index of the ratchet, \(i\).
-Cipher-Text|0x12|String|The cipher-text, Xi, of the message
+Cipher-Text|0x12|String|The cipher-text of the message, \(X_i\).
 
 Within the payload, integers are encoded using a variable length encoding. Each
 integer is encoded as a sequence of bytes with the high bit set followed by a

content/olm-megolm/olm.md

@@ -17,12 +17,12 @@ side of an \(=\) it means that the output is split.
 When this document uses \(\operatorname{ECDH}\left(K_A,K_B\right)\) it means
 that each party computes a Diffie-Hellman agreement using their private key 
 and the remote party's public key.
-So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{public},K_A^{private}\right)\)
+So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{\mathit{public}},K_A^{\mathit{private}}\right)\)
-and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{public},K_B^{private}\right)\).
+and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{\mathit{public}},K_B^{\mathit{private}}\right)\).
 
-Where this document uses \(\operatorname{HKDF}\left(salt,IKM,info,L\right)\) it
+Where this document uses \(\operatorname{HKDF}\left(\mathit{salt},\mathit{IKM},\mathit{info},L\right)\) it
 refers to the [HMAC-based key derivation function][] with a salt value of
-\(salt\), input key material of \(IKM\), context string \(info\),
+\(\mathit{salt}\), input key material of \(\mathit{IKM}\), context string \(\mathit{info}\),
 and output keying material length of \(L\) bytes.
 
 ## The Olm Algorithm
@@ -226,9 +226,9 @@ significant bits are stored in the first byte.
 
 **Name**|**Tag**|**Type**|**Meaning**
 :-----:|:-----:|:-----:|:-----:
-Ratchet-Key|0x0A|String|The public part of the ratchet key, Ti, of the message
+Ratchet-Key|0x0A|String|The public part of the ratchet key of the message, \(T_i\).
-Chain-Index|0x10|Integer|The chain index, j, of the message
+Chain-Index|0x10|Integer|The chain index of the message, \(j\).
-Cipher-Text|0x22|String|The cipher-text, Xi, j, of the message
+Cipher-Text|0x22|String|The cipher-text of the message, \(X_{i,j}\).
 
 The length of the MAC is determined by the authenticated encryption algorithm
 being used. (Olm version 1 uses [HMAC-SHA-256][], truncated to 8 bytes). The
@@ -251,9 +251,9 @@ The payload uses the same key-value format as for normal messages.
 
 **Name**|**Tag**|**Type**|**Meaning**
 :-----:|:-----:|:-----:|:-----:
-One-Time-Key|0x0A|String|The public part of Bob's single-use key, Eb.
+One-Time-Key|0x0A|String|The public part of Bob's single-use key, \(E_B\).
-Base-Key|0x12|String|The public part of Alice's single-use key, Ea.
+Base-Key|0x12|String|The public part of Alice's single-use key, \(E_A\).
-Identity-Key|0x1A|String|The public part of Alice's identity key, Ia.
+Identity-Key|0x1A|String|The public part of Alice's identity key, \(I_A\).
 Message|0x22|String|An embedded Olm message with its own version and MAC.
 
 ## Olm Authenticated Encryption
@@ -268,13 +268,13 @@ message key using [HKDF-SHA-256][] using the default salt and an info of
 
 \[
 \begin{aligned}
-    AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j}
+    \mathit{AES\_KEY}_{i,j}\;\parallel\;\mathit{HMAC\_KEY}_{i,j}\;\parallel\;\mathit{AES\_IV}_{i,j}
     &= \operatorname{HKDF}\left(0,M_{i,j},\text{``OLM\_KEYS"},80\right)
 \end{aligned}
 \]
 
-The plain-text is encrypted with AES-256, using the key \(AES\_KEY_{i,j}\)
+The plain-text is encrypted with AES-256, using the key \(\mathit{AES\_KEY}_{i,j}\)
-and the IV \(AES\_IV_{i,j}\) to give the cipher-text, \(X_{i,j}\).
+and the IV \(\mathit{AES\_IV}_{i,j}\) to give the cipher-text, \(X_{i,j}\).
 
 Then the entire message (including the Version Byte and all Payload Bytes) are
 passed through [HMAC-SHA-256][]. The first 8 bytes of the MAC are appended to the message.