Merge pull request #1283 from uhoreg/fix_event_subtype

improve display of event subtypes

changelogs/client_server/newsfragments/1283.clarification

@@ -0,0 +1 @@
+Improve display of event subtypes.

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
 

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

@@ -10,7 +10,7 @@ room itself such as a room name and topic.
 
 #### Events
 
-{{% event event="m.room.message" %}}
+{{% event event="m.room.message" desired_example_name="m.room.message$m.text" %}}
 
 {{% event event="m.room.name" %}}
 

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
 

layouts/partials/events/example.html

@@ -0,0 +1,17 @@
+{{/*
+
+  Renders an event example.  Resolves `$ref`s, serializes as JSON, and ensures
+  that it can be included in HTML.
+
+  This partial is called with the example event object as its context.
+
+*/}}
+
+{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" . "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 }}
+```

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 }}{{ . | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
   </h1>
 
   <hr/>
@@ -72,11 +74,16 @@
     */}}
     {{ 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") }}
+            {{ partial "events/example" $example }}
-```json
-{{ jsonify (dict "indent" "  ") $example_content }}
-```
         {{ end }}
+    {{/*
+      If `$desired_example_name` is not given, we will include any
+      example that is equal to the event name. Normally, this would
+      be handled by the case below, but that case does not work if
+      the event name includes a "$".
+    */}}
+    {{ else if eq $event_name $example_name }}
+        {{ partial "events/example" $example }}
     {{/*
       If `$desired_example_name` is not given, we will include any
       examples whose first part (before "$") matches the event name
@@ -86,14 +93,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") }}
+             {{ partial "events/example" $example }}
-            {{ $example_json := jsonify (dict "indent" "  ") $example_content }}
-            {{ $example_json = replace $example_json "\\u003c" "<" }}
-            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
         {{ end }}
     {{ end }}
 {{ end }}

layouts/shortcodes/event.html

@@ -2,10 +2,23 @@
 
   This template is used to render an event.
 
-  It expects to be passed an `event` parameter, which is the name of a schema file under
+  It takes the following parameters:
-  "data/event-schemas/schema". The file extension is omitted. For example:
 
-      {{% event event="m.accepted_terms" %}}
+    * `event` (required): the name of a schema file under "data/event-schemas/schema".
+      The file extension is omitted. For example:
+
+        {{% event event="m.accepted_terms" %}}
+
+    * `desired_example_name` (optional): the name of the example file to use under
+      "data/event-schemas/examples", without the file extension.  If omitted
+      defaults to the example file with the same name as the `event` parameter, and
+      (if the name does not contain a "$"), all examples that begin with the name
+      given by the `event` parameter followed by a "$".  For example, if the
+      `event` parameter is "m.foo", then by default it will include the "m.foo"
+      example along with any examples starting with "m.foo$".
+
+    * `title` (optional): the title to use for the event.  Defaults to the name
+      given in the `event` parameter.
 
   This template replaces the old {{*_event}} template.
 
@@ -17,4 +30,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 "desired_example_name" .Params.desired_example_name "title" .Params.title)}}