From 99cd692ed0902a9a02d79be4b90bf08755384171 Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubertc@matrix.org>
Date: Wed, 12 Oct 2022 15:49:21 -0400
Subject: [PATCH] improve display of event subtypes

---
 .../modules/end_to_end_encryption.md          |  4 ++--
 .../modules/server_notices.md                 |  2 +-
 layouts/partials/events/example.html          |  8 +++++++
 layouts/partials/events/render-event.html     | 22 +++++++------------
 layouts/shortcodes/event.html                 |  2 +-
 5 files changed, 20 insertions(+), 18 deletions(-)
 create mode 100644 layouts/partials/events/example.html

diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index 10f21e86..99a138c1 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -736,7 +736,7 @@ following error codes are used in addition to those already specified:
 -   `m.mismatched_commitment`: The hash commitment did not match.
 -   `m.mismatched_sas`: The SAS did not match.
 
-{{% event event="m.key.verification.start$m.sas.v1" %}}
+{{% event event="m.key.verification.start$m.sas.v1" title="`m.key.verification.start` with `method: m.sas.v1`" %}}
 
 {{% event event="m.key.verification.accept" %}}
 
@@ -1145,7 +1145,7 @@ base64).
 
 ###### Verification messages specific to QR codes
 
-{{% event event="m.key.verification.start$m.reciprocate.v1" %}}
+{{% event event="m.key.verification.start$m.reciprocate.v1" title="`m.key.verification.start` with `method: m.reciprocate.v1`" %}}
 
 #### Sharing keys between devices
 
diff --git a/content/client-server-api/modules/server_notices.md b/content/client-server-api/modules/server_notices.md
index b0e2fa22..05f9e270 100644
--- a/content/client-server-api/modules/server_notices.md
+++ b/content/client-server-api/modules/server_notices.md
@@ -35,7 +35,7 @@ maximum. New connections are being refused by the server. What defines
 "active" is left as an implementation detail, however servers are
 encouraged to treat syncing users as "active".
 
-{{% event event="m.room.message$m.server_notice" %}}
+{{% event event="m.room.message$m.server_notice" title="`m.room.message` with `msgtype: m.server_notice`" %}}
 
 #### Client behaviour
 
diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html
new file mode 100644
index 00000000..95e17e22
--- /dev/null
+++ b/layouts/partials/events/example.html
@@ -0,0 +1,8 @@
+{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .example "path" "event-schemas/examples") }}
+{{ $example_json := jsonify (dict "indent" "  ") $example_content }}
+{{ $example_json = replace $example_json "\\u003c" "<" }}
+{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
+
+```json
+{{ $example_json }}
+```
diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html
index 5e9f5c13..73421741 100644
--- a/layouts/partials/events/render-event.html
+++ b/layouts/partials/events/render-event.html
@@ -2,11 +2,13 @@
 
   Renders a single event, given:
 
-    * `event_name`: the name we want to display for the event
+    * `event_name`: the name to use for the event
     * `event_data`: the event specification
     * `desired_example_name` (optional): the exact name of the examples to render.
     If `desired_example_name` is omitted we render all examples
     whose names start with the `event_name`.
+    * `title` (optional): the title to display.  May contain markdown.  Defaults to
+    `event_name` wrapped in a <code> element
 
 */}}
 
@@ -20,7 +22,7 @@
 <summary>
 
   <h1 id="{{ anchorize $event_name }}">
-   <code>{{ $event_name }}</code>
+   {{ with .title }}{{ $.title | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
   </h1>
 
   <hr/>
@@ -72,11 +74,10 @@
     */}}
     {{ if $desired_example_name }}
         {{ if eq $example_name $desired_example_name }}
-            {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }}
-```json
-{{ jsonify (dict "indent" "  ") $example_content }}
-```
+            {{ partial "events/example" (dict "example" $example)}}
         {{ end }}
+    {{ else if eq $event_name $example_name }}
+        {{ partial "events/example" (dict "example" $example)}}
     {{/*
       If `$desired_example_name` is not given, we will include any
       examples whose first part (before "$") matches the event name
@@ -86,14 +87,7 @@
         {{ $pieces := split $example_name "$" }}
         {{ $example_base_name := index $pieces 0 }}
         {{ if eq $event_name $example_base_name }}
-            {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }}
-            {{ $example_json := jsonify (dict "indent" "  ") $example_content }}
-            {{ $example_json = replace $example_json "\\u003c" "<" }}
-            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
+             {{ partial "events/example" (dict "example" $example)}}
         {{ end }}
     {{ end }}
 {{ end }}
diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html
index 71c9c534..5ee32605 100644
--- a/layouts/shortcodes/event.html
+++ b/layouts/shortcodes/event.html
@@ -17,4 +17,4 @@
 {{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }}
 {{ $event_data := partial "json-schema/resolve-allof" $event_data }}
 
-{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data)}}
+{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data "title" .Params.title)}}