Merge branch 'rav/megolm_doc_format' into 'master'

Update megolm.md

See merge request matrix-org/olm!6

1 files changed, 17 insertions, 16 deletions

diff --git a/docs/megolm.md b/docs/megolm.md
index ec98001..eaae7e0 100644
--- a/docs/megolm.md
+++ b/docs/megolm.md
@@ -69,8 +69,8 @@ R_{i,3} &=
 
 where $`H_0`$, $`H_1`$, $`H_2`$, and $`H_3`$ are different hash
 functions. In summary: every $`2^8`$ iterations, $`R_{i,3}`$ is
-reseeded from $`R_{i,2}`$. Every $`2^16`$ iterations, $`R_{i,2}`$
-and $`R_{i,3}`$ are reseeded from $`R_{i,1}`$. Every $`2^24`$
+reseeded from $`R_{i,2}`$. Every $`2^{16}`$ iterations, $`R_{i,2}`$
+and $`R_{i,3}`$ are reseeded from $`R_{i,1}`$. Every $`2^{24}`$
 iterations, $`R_{i,1}`$, $`R_{i,2}`$ and $`R_{i,3}`$ are reseeded
 from $`R_{i,0}`$.
 
@@ -119,26 +119,27 @@ copy of the counter, ratchet, and public key.
 
 ### Message encryption
 
-This version of Megolm uses AES-256_ in CBC_ mode with [PKCS#7][] padding and
-HMAC-SHA-256_ (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key,
+This version of Megolm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding and
+[HMAC-SHA-256][] (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key,
 and 128 bit AES IV are derived from the megolm ratchet $`R_i`$:
 
 ```math
 \begin{aligned}
-AES\_KEY_{i}\;\parallel\;HMAC\_KEY_{i}\;\parallel\;AES\_IV_{i}
-    &= HKDF\left(0,\,R_{i},\text{"MEGOLM\_KEYS"},\,80\right) \\
+ \mathit{AES\_KEY}_{i}\;\parallel\;\mathit{HMAC\_KEY}_{i}\;\parallel\;\mathit{AES\_IV}_{i}
+    &= \operatorname{HKDF}\left(0,\,R_{i},\text{"MEGOLM\_KEYS"},\,80\right) \\
 \end{aligned}
 ```
 
 where $`\parallel`$ represents string splitting, and
-$`HKDF\left(salt,\,IKM,\,info,\,L\right)`$ refers to the [HMAC-based key
+$`\operatorname{HKDF}\left(\mathit{salt},\,\mathit{IKM},\,\mathit{info},\,L\right)`$
+refers to the [HMAC-based key
 derivation function][] using using [SHA-256][] as the hash function
-([HKDF-SHA-256][]) with a salt value of $`salt`$, input key material of
-$`IKM`$, context string $`info`$, and output keying material length of
+([HKDF-SHA-256][]) with a salt value of $`\mathit{salt}`$, input key material of
+$`\mathit{IKM}`$, context string $`\mathit{info}`$, and output keying material length of
 $`L`$ bytes.
 
-The plain-text is encrypted with AES-256, using the key $`AES\_KEY_{i}`$
-and the IV $`AES\_IV_{i}`$ to give the cipher-text, $`X_{i}`$.
+The plain-text is encrypted with AES-256, using the key $`\mathit{AES\_KEY}_{i}`$
+and the IV $`\mathit{AES\_IV}_{i}`$ to give the cipher-text, $`X_{i}`$.
 
 The ratchet index $`i`$, and the cipher-text $`X_{i}`$, are then packed
 into a message as described in [Message format](#message-format). Then the entire message
@@ -160,14 +161,14 @@ described in [The Megolm ratchet algorithm](#the-megolm-ratchet-algorithm), usin
 
 ```math
 \begin{aligned}
-    H_0(A) &\equiv HMAC(A,\text{"\x00"}) \\
-    H_1(A) &\equiv HMAC(A,\text{"\x01"}) \\
-    H_2(A) &\equiv HMAC(A,\text{"\x02"}) \\
-    H_3(A) &\equiv HMAC(A,\text{"\x03"}) \\
+    H_0(A) &\equiv \operatorname{HMAC}(A,\text{"\x00"}) \\
+    H_1(A) &\equiv \operatorname{HMAC}(A,\text{"\x01"}) \\
+    H_2(A) &\equiv \operatorname{HMAC}(A,\text{"\x02"}) \\
+    H_3(A) &\equiv \operatorname{HMAC}(A,\text{"\x03"}) \\
 \end{aligned}
 ```
 
-where $`HMAC(A, T)`$ is the HMAC-SHA-256 of ``T``, using ``A`` as the
+where $`\operatorname{HMAC}(A, T)`$ is the HMAC-SHA-256 of ``T``, using ``A`` as the
 key.
 
 For outbound sessions, the updated ratchet and counter are stored in the