From a565becdb176725d52479d0b8ac0998909392b66 Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Fri, 2 Nov 2018 16:30:42 -0700
Subject: [PATCH] Editorial: Standardize event definitions/links

---
 index.bs | 124 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 64 insertions(+), 60 deletions(-)

diff --git a/index.bs b/index.bs
index 1e89305..9065abf 100644
--- a/index.bs
+++ b/index.bs
@@ -281,13 +281,13 @@ request.onsuccess = function() {
 <aside class=example id=handling-versionchange>
 A single database can be used by multiple clients (pages and workers)
 simultaneously &mdash; transactions ensure they don't clash while reading and writing.
-If a new client wants to upgrade the database (via the "<code>[=upgradeneeded=]</code>"
+If a new client wants to upgrade the database (via the <a event>`upgradeneeded`</a>
 event), it cannot do so until all other clients close their connection to the
 current version of the database.
 
 To avoid blocking a new client from upgrading, clients can listen for the
-[=connection/version change event=]. This fires when another client is wanting to upgrade the
-database. To allow this to continue, react to the "`versionchange`" event by doing
+<a event>`versionchange`</a> event. This fires when another client is wanting to upgrade the
+database. To allow this to continue, react to the <a event>`versionchange`</a> event by doing
 something that ultimately closes this client's [=/connection=] to the database.
 
 One way of doing this is to reload the page:
@@ -336,10 +336,10 @@ function stopUsingTheDatabase() {
 }
 ```
 
-The new client (the one attempting the upgrade) can use the "`blocked`" event to
-detect if other clients are preventing the upgrade from happening. The "`blocked`"
+The new client (the one attempting the upgrade) can use the <a event>`blocked`</a> event to
+detect if other clients are preventing the upgrade from happening. The <a event>`blocked`</a>
 event fires if other clients still hold a connection to the database after their
-"`versionchange`" events have fired.
+<a event>`versionchange`</a> events have fired.
 
 ```js
 var request = indexedDB.open("library", 4); // Request version 4.
@@ -490,7 +490,7 @@ running.
 A [=/connection=]'s [=get the parent=] algorithm returns
 null.
 
-A <dfn>version change event</dfn> will be fired at an open
+A <dfn event>`versionchange`</dfn> will be fired at an open
 [=/connection=] if an attempt is made to upgrade or delete the
 [=database=]. This gives the [=/connection=] the opportunity to close
 to allow the upgrade or delete to proceed.
@@ -509,7 +509,7 @@ storing data in a [=database=].
 
 Each database has a set of [=/object stores=]. The set of [=/object
 stores=] can be changed, but only using an [=/upgrade transaction=],
-i.e. in response to an <code>[=upgradeneeded=]</code> event. When a
+i.e. in response to an <a event>`upgradeneeded`</a> event. When a
 new database is created it doesn't contain any [=/object stores=].
 
 An [=/object store=] has a <dfn>list of records</dfn> which hold the
@@ -972,7 +972,7 @@ following:
     stores and indexes. It is the only type of transaction that can do
     so. This type of transaction can't be manually created, but
     instead is created automatically when an
-    <code>[=upgradeneeded=]</code> event is fired.
+    <a event>`upgradeneeded`</a> event is fired.
   </dd>
 </dl>
 
@@ -999,7 +999,6 @@ a [=/transaction=] with [=transaction/mode=] {{"readonly"}}.
 A <dfn>read/write transaction</dfn>
 is a [=/transaction=] with [=transaction/mode=] {{"readwrite"}}.
 
-
 <!-- ============================================================ -->
 ### Transaction Lifetime ### {#transaction-lifetime-concept}
 <!-- ============================================================ -->
@@ -1091,6 +1090,12 @@ The <dfn>lifetime</dfn> of a
     implementation crashing or the user taking some explicit action to
     cancel it, the implementation must [=transaction/abort=] the transaction.
 
+An event with type <dfn event>`complete`</dfn> is fired at
+a [=/transaction=] that has successfully [=transaction/committed=].
+
+An event with type <dfn event>`abort`</dfn> is fired at
+a [=/transaction=] that has [=transaction/aborted=].
+
 The following constraints define when a [=/transaction=] can be
 [=transaction/started=]:
 
@@ -1199,7 +1204,7 @@ An [=/upgrade transaction=] is automatically created when running the
 steps to [=run an upgrade transaction=] after a [=/connection=]
 is opened to a [=/database=], if a [=database/version=] greater than
 the current [=database/version=] is specified. This [=/transaction=]
-will be active inside the <code>[=upgradeneeded=]</code> event
+will be active inside the <a event>`upgradeneeded`</a> event
 handler.
 
 <aside class=note>
@@ -1209,7 +1214,7 @@ handler.
   An [=/upgrade transaction=] is exclusive. The steps to [=open a
   database=] ensure that only one [=/connection=] to the database is
   open when an [=/upgrade transaction=] is running.
-  The <code>[=upgradeneeded=]</code> event isn't fired, and thus the
+  The <a event>`upgradeneeded`</a> event isn't fired, and thus the
   [=/upgrade transaction=] isn't started, until all other
   [=/connections=] to the same [=/database=] are closed. This ensures
   that all previous transactions are [=transaction/finished=]. As long
@@ -1253,12 +1258,12 @@ request=].
 When a request is made, a new [=/request=] is returned with its [=request/done
 flag=] unset. If a request completes successfully, the [=request/done flag=]
 is set, the [=request/result=] is set to the result of the request,
-and an event with type `success` is fired at the
+and an event with type <dfn event>`success`</dfn> is fired at the
 [=/request=].
 
 If an error occurs while performing the operation, the [=request/done flag=]
 is set, the [=request/error=] is set to the error, and an event with
-type `error` is fired at the request.
+type <dfn event>`error`</dfn> is fired at the request.
 
 A [=/request=]'s [=get the parent=] algorithm returns the request's
 [=request/transaction=].
@@ -1268,7 +1273,7 @@ A [=/request=]'s [=get the parent=] algorithm returns the request's
   [=cursor=] is iterated, the success of the iteration is reported
   on the same [=/request=] object used to open the cursor. And when
   an [=/upgrade transaction=] is necessary, the same [=open
-  request=] is used for both the <code>[=upgradeneeded=]</code>
+  request=] is used for both the <a event>`upgradeneeded`</a>
   event and final result of the open operation itself. In some cases,
   the request's [=request/done flag=] will be unset then set again, and the
   [=request/result=] can change or [=request/error=] could be set insead.
@@ -1280,15 +1285,15 @@ A [=/request=]'s [=get the parent=] algorithm returns the request's
 
 An <dfn>open request</dfn> is a special type of [=/request=] used
 when opening a [=/connection=] or deleting a [=database=].
-In addition to `success` and `error` events,
-<dfn>`blocked`</dfn> and <dfn>`upgradeneeded`</dfn> may be fired at an [=open
+In addition to <a event>`success`</a> and <a event>`error`</a> events,
+<dfn event>`blocked`</dfn> and <dfn event>`upgradeneeded`</dfn> events may be fired at an [=open
 request=] to indicate progress.
 
 The [=request/source=] of an [=open request=]
 is always null.
 
 The [=request/transaction=] of an [=open request=] is null
-unless an <code>[=upgradeneeded=]</code> event has been fired.
+unless an <a event>`upgradeneeded`</a> event has been fired.
 
 An [=open request=]'s [=get the parent=] algorithm returns null.
 
@@ -2070,16 +2075,15 @@ must return {{"pending"}} if the [=request/done flag=] is unset, and
 
 
 The <dfn attribute for=IDBRequest>onsuccess</dfn> attribute is the
-event handler for the `success` event.
+event handler for the <a event>`success`</a> event.
 
 The <dfn attribute for=IDBRequest>onerror</dfn> attribute is the event
-handler for the `error` event.
+handler for the <a event>`error`</a> event.
 
 
 Methods on {{IDBDatabase}} that return a [=open request=] use an
 extended interface to allow listening to the
-<code>[=request/blocked=]</code> event and
-<code>[=upgradeneeded=]</code> event.
+<a event>`blocked`</a> and <a event>`upgradeneeded`</a> events.
 
 <xmp class=idl>
 [Exposed=(Window,Worker)]
@@ -2091,11 +2095,11 @@ interface IDBOpenDBRequest : IDBRequest {
 </xmp>
 
 The <dfn attribute for=IDBOpenDBRequest>onblocked</dfn> attribute is
-the event handler for the <code>[=request/blocked=]</code> event.
+the event handler for the <a event>`blocked`</a> event.
 
 The <dfn attribute for=IDBOpenDBRequest>onupgradeneeded</dfn>
 attribute is the event handler for the
-<code>[=upgradeneeded=]</code> event.
+<a event>`upgradeneeded`</a> event.
 
 
 <!-- ============================================================ -->
@@ -2205,8 +2209,8 @@ dictionary IDBDatabaseInfo {
         with the specified version. If the database already exists
         with a lower version and there are open [=/connections=]
         that don't close in response to a
-        `versionchange` event, the request will be
-        [=request/blocked=] until all they close, then an upgrade
+        <a event>`versionchange`</a> event, the request will be
+        blocked until all they close, then an upgrade
         will occur. If the database already exists with a higher
         version the request will fail. If the request is
         successful |request|'s {{IDBRequest/result}} will
@@ -2218,8 +2222,8 @@ dictionary IDBDatabaseInfo {
         Attempts to delete the named [=/database=]. If the
         database already exists and there are open
         [=/connections=] that don't close in response to a
-        `versionchange` event, the request will be
-        [=request/blocked=] until all they close. If the request
+        <a event>`versionchange`</a> event, the request will be
+        blocked until all they close. If the request
         is successful |request|'s {{IDBRequest/result}}
         will be null.
     </dd>
@@ -2277,14 +2281,14 @@ when invoked, must run these steps:
             1. Set |request|'s [=request/result=] to undefined.
             1. Set |request|'s [=request/error=] to |result|.
             1. Set |request|'s [=request/done flag=].
-            1. [=Fire an event=] named `error` at |request| with its
+            1. [=Fire an event=] named <a event>`error`</a> at |request| with its
                 {{Event/bubbles}} and {{Event/cancelable}} attributes initialized to true.
 
         1. Otherwise, run these steps:
 
             1. Set |request|'s [=request/result=] to |result|.
             1. Set |request|'s [=request/done flag=].
-            1. [=Fire an event=] named `success` at |request|.
+            1. [=Fire an event=] named <a event>`success`</a> at |request|.
 
             <aside class=note>
                 If the steps above resulted in an [=/upgrade
@@ -2293,7 +2297,7 @@ when invoked, must run these steps:
                 case where another version upgrade is about to happen,
                 the success event is fired on the connection first so
                 that the script gets a chance to register a listener
-                for the `versionchange` event.
+                for the <a event>`versionchange`</a> event.
             </aside>
 
             <details class=note>
@@ -2335,14 +2339,14 @@ when invoked, must run these steps:
             set |request|'s [=request/error=] to |result|,
             set |request|'s [=request/done flag=],
             and [=fire an event=]
-            named `error` at |request| with
+            named <a event>`error`</a> at |request| with
             its {{Event/bubbles}} and {{Event/cancelable}} attributes initialized to true.
 
         1. Otherwise,
             set |request|'s [=request/result=] to undefined,
             set |request|'s [=request/done flag=],
             and [=fire a version change event=] named
-            `success` at [=/request=] with |result| and
+            <a event>`success`</a> at [=/request=] with |result| and
             null.
 
             <details class=note>
@@ -2355,7 +2359,7 @@ when invoked, must run these steps:
               transaction before dispatch and deactivate the
               transaction after dispatch &mdash; do not apply.
 
-              Also, the `success` event here is a
+              Also, the <a event>`success`</a> event here is a
               {{IDBVersionChangeEvent}} which includes the
               {{IDBVersionChangeEvent/oldVersion}} and
               {{IDBVersionChangeEvent/newVersion}} details.
@@ -2446,7 +2450,7 @@ interface represents a [=/connection=] to a [=database=].
 An {{IDBDatabase}} object must not be garbage collected if its
 associated [=/connection=]'s [=close pending flag=] is unset and it
 has one or more event listeners registers whose type is one of
-`abort`, `error`, or `versionchange`.
+<a event>`abort`</a>, <a event>`error`</a>, or <a event>`versionchange`</a>.
 If an {{IDBDatabase}} object is garbage collected, the associated
 [=/connection=] must be [=connection/closed=].
 
@@ -2740,16 +2744,16 @@ must run these steps:
 </div>
 
 The <dfn attribute for=IDBDatabase>onabort</dfn> attribute is the
-event handler for the `abort` event.
+event handler for the <a event>`abort`</a> event.
 
 The <dfn attribute for=IDBDatabase>onclose</dfn> attribute is the
-event handler for the `close` event.
+event handler for the <a event>`close`</a> event.
 
 The <dfn attribute for=IDBDatabase>onerror</dfn> attribute is the
-event handler for the `error` event.
+event handler for the <a event>`error`</a> event.
 
 The <dfn attribute for=IDBDatabase>onversionchange</dfn> attribute is
-the event handler for the `versionchange` event.
+the event handler for the <a event>`versionchange`</a> event.
 
 
 <!-- ============================================================ -->
@@ -4640,7 +4644,7 @@ does not modify the contents of the database.
 
 <div class=note>
   The following methods advance a [=cursor=]. Once the cursor has
-  advanced, a `success` event will be fired at the
+  advanced, a <a event>`success`</a> event will be fired at the
   same {{IDBRequest}} returned when the cursor was opened. The
   {{IDBRequest/result}} will be the same cursor if a [=object-store/record=] was
   in range, or `undefined` otherwise.
@@ -5188,20 +5192,20 @@ must run these steps:
 </div>
 
 The <dfn attribute for=IDBTransaction>onabort</dfn> attribute is the
-event handler for the `abort` event.
+event handler for the <a event>`abort`</a> event.
 
 The <dfn attribute for=IDBTransaction>oncomplete</dfn> attribute is
-the event handler for the `complete` event.
+the event handler for the <a event>`complete`</a> event.
 
 The <dfn attribute for=IDBTransaction>onerror</dfn> attribute is the
-event handler for the `error` event.
+event handler for the <a event>`error`</a> event.
 
 <aside class=note>
   To determine if a [=/transaction=] has completed successfully,
-  listen to the [=/transaction=]'s `complete` event
-  rather than the `success` event of a particular
+  listen to the [=/transaction=]'s <a event>`complete`</a> event
+  rather than the <a event>`success`</a> event of a particular
   [=/request=], because the [=/transaction=] can still fail after
-  the `success` event fires.
+  the <a event>`success`</a> event fires.
 </aside>
 
 
@@ -5253,13 +5257,13 @@ database |name|, a database |version|, and a |request|.
 
     1. For each |entry| in |openConnections| that does not have its
         [=close pending flag=] set, [=queue a task=] to [=fire a
-        version change event=] named `versionchange` at
+        version change event=] named <a event>`versionchange`</a> at
         |entry| with |db|'s [=database/version=] and |version|.
 
         <aside class=note>
           Firing this event might cause one or more of the other
           objects in |openConnections| to be closed, in which case the
-          `versionchange` event is not fired at those
+          <a event>`versionchange`</a> event is not fired at those
           objects, even if that hasn't yet been done.
         </aside>
 
@@ -5267,7 +5271,7 @@ database |name|, a database |version|, and a |request|.
 
     1. If any of the [=/connections=] in |openConnections| are still
         not closed, [=queue a task=] to [=fire a version change
-        event=] named <code>[=request/blocked=]</code> at |request| with
+        event=] named <a event>`blocked`</a> at |request| with
         |db|'s [=database/version=] and |version|.
 
     1. <span id="version-change-close-block">Wait</span> until all
@@ -5311,10 +5315,10 @@ optional |forced flag|.
     Once they are complete, |connection| is [=connection/closed=].
 
 1. If the |forced flag| is set, then [=fire an event=] named
-    `close` at |connection|.
+    <a event>`close`</a> at |connection|.
 
     <aside class=note>
-      The "`close`" event only fires if the connection closes
+      The <a event>`close`</a> event only fires if the connection closes
       abnormally, e.g. if the origin's storage is cleared, or there is
       corruption or an I/O error. If {{IDBDatabase/close()}} is called explicitly
       the event *does not* fire.
@@ -5363,13 +5367,13 @@ requested the [=database=] to be deleted, a database |name|, and a
 
 1. For each |entry| in |openConnections| that does not have its
     [=close pending flag=] set, [=queue a task=] to [=fire a version
-    change event=] named `versionchange` at |entry| with
+    change event=] named <a event>`versionchange`</a> at |entry| with
     |db|'s [=database/version=] and null.
 
     <aside class=note>
       Firing this event might cause one or more of the other objects
       in |openConnections| to be closed, in which case the
-      `versionchange` event is not fired at those
+      <a event>`versionchange`</a> event is not fired at those
       objects, even if that hasn't yet been done.
     </aside>
 
@@ -5377,7 +5381,7 @@ requested the [=database=] to be deleted, a database |name|, and a
 
 1. If any of the [=/connections=] in |openConnections| are still not
     closed, [=queue a task=] to [=fire a version change event=] named
-    <code>[=request/blocked=]</code> at |request| with |db|'s
+    <a event>`blocked`</a> at |request| with |db|'s
     [=database/version=] and null.
 
 1. <span id="delete-close-block">Wait</span> until all
@@ -5417,14 +5421,14 @@ This algorithm takes one argument, the |transaction| to commit.
     1. If |transaction| is an [=/upgrade transaction=], set the
         [=database=]'s [=database/upgrade transaction=] to null.
 
-    1. [=Fire an event=] named `complete` at |transaction|.
+    1. [=Fire an event=] named <a event>`complete`</a> at |transaction|.
 
         <aside class=note>
           Even if an exception is thrown from one of the event handlers of
           this event, the transaction is still committed since writing the
           database changes happens before the event takes places. Only
           after the transaction has been successfully written is the
-          "`complete`" event fired.
+          <a event>`complete`</a> event fired.
         </aside>
 
     1. If |transaction| is an [=/upgrade transaction=], then
@@ -5472,12 +5476,12 @@ takes two arguments: the |transaction| to abort, and |error|.
     1. Set |request|'s [=request/result=] to undefined.
     1. Set |request|'s [=request/error=] to a newly
         <a for=exception>created</a> "{{AbortError}}" {{DOMException}}.
-    1. [=Fire an event=] named `error` at |request|
+    1. [=Fire an event=] named <a event>`error`</a> at |request|
         with its {{Event/bubbles}} and {{Event/cancelable}}
         attributes initialized to true.
 
     <aside class=note>
-      This does not always result in any `error` events
+      This does not always result in any <a event>`error`</a> events
       being fired. For example if a transaction is aborted due to an
       error while [=transaction/committing=] the transaction,
       or if it was the last remaining request that failed.
@@ -5488,7 +5492,7 @@ takes two arguments: the |transaction| to abort, and |error|.
     1. If |transaction| is an [=/upgrade transaction=], set the
         [=database=]'s [=database/upgrade transaction=] to null.
 
-    1. [=Fire an event=] named `abort` at |transaction|
+    1. [=Fire an event=] named <a event>`abort`</a> at |transaction|
         with its {{Event/bubbles}} attribute initialized to true.
 
     1. If |transaction| is an [=/upgrade transaction=], then:
@@ -5606,7 +5610,7 @@ for the [=database=], and a |request|.
     1. Set |transaction|'s [=transaction/active flag=].
     1. Let |didThrow| be the result of running the steps to
         [=fire a version change event=] named
-        <code>[=upgradeneeded=]</code> at |request| with |old
+        <a event>`upgradeneeded`</a> at |request| with |old
         version| and |version|.
     1. Unset |transaction|'s [=transaction/active flag=].
     1. If |didThrow| is set, run the steps to [=abort a