update ABNF and header examples (#37)

* update ABNF and header examples

* explicitly call out server-timing-param-name and server-timing-param-value

* map processing steps to named parameters in the header

* make '=' and value mandatory in the ABNF

* clean up words addressing duplicate names

* address cr feedback

* Use respec for linking

index.html

@@ -70,25 +70,30 @@
 The <dfn>Server-Timing header field</dfn> is used to communicate one or more metrics and descriptions for the given request-response cycle. The ABNF (Augmented Backus-Naur Form) [[!RFC5234]] syntax for the <a>Server-Timing header field</a> is as follows:
 
 ```ABNF
-  Server-Timing        = #server-timing-metric
-  server-timing-metric = metric  [ OWS ";" OWS description ]
-  metric               = metric-name [ OWS "=" OWS metric-value ]
-  metric-name          = token
-  metric-value         = *DIGIT [ "." 1*DIGIT ]
-  description          = token | quoted-string
+  Server-Timing             = #server-timing-metric
+  server-timing-metric      = metric-name *( OWS ";" OWS server-timing-param )
+  metric-name               = token
+  server-timing-param       = server-timing-param-name OWS "=" OWS server-timing-param-value
+  server-timing-param-name  = token
+  server-timing-param-value = token / quoted-string
 ```
 
-* Each metric MUST have a name.
-  * Metric names MAY be repeated.
-  * Metric names are defined by the server.
-* Each metric MAY have an optional numeric value.
-* Each metric MAY have an optional description.
-* The user agent MAY surface provided metrics in any order - i.e. the order of metrics in the HTTP header field is not significant.
+See [[!RFC7230]] for definitions of `#`, `*`, `OWS`, `token`, and `quoted-string`.
 
-See [[!RFC7230]] for definitions of `#`, `OWS`, `token`, `DIGIT`, and `quoted-string`.
+A response MAY have multiple server-timing-metric entries with the same metric-name, and the user agent MUST process and expose all such entries.
+
+The user agent MAY surface provided metrics in any order - i.e. the order of metrics in the HTTP header field is not significant.
+
+This header field is defined with an extensible syntax to allow for future parameters. A user agent that does not recognize particular server-timing-param-name in the Server-Timing header field of a response MUST ignore those tokens and continue processing instead of signaling an error.
+
+To avoid any possible ambiguity, individual server-timing-param-name SHOULD NOT appear multiple times within a server-timing-metric. If any parameter is specified more than once, only the first instance is to be considered. All subsequent occurrences MUST be ignored without signaling an error or otherwise altering the processing of the server-timing-metric. This is the only case in which the ordering of parameters within a server-timing-metric is considered to be significant.
+
+<p data-link-for="PerformanceServerTiming">
+This specification establishes the server-timing-params for server-timing-param-names <a>duration</a> and <a>description</a>, both optional.
+</p>
 
 <div class="note">
-  - To minimize the HTTP overhead the provided metrics and descriptions should be kept as short as possible - e.g. use abbreviations and omit optional values where possible.
+  - To minimize the HTTP overhead the provided names and descriptions should be kept as short as possible - e.g. use abbreviations and omit optional values where possible.
 
   - Because there can be no guarantee of clock synchronization between client, server, and intermediaries, it is impossible to map a meaningful `startTime` onto the clients timeline. For that reason, any `startTime` attribution is purposely omitted from this specification. If the developers want to establish a relationship between multiple entries, they can do so by communicating custom data via metric names and/or descriptions.
 
@@ -111,13 +116,13 @@
   When <dfn>toJSON</dfn> is called, run [[!WEBIDL]]'s <a data-cite="WEBIDL#default-tojson-operation">default toJSON operation</a>.
 
   ### <dfn>name</dfn> attribute
-  The <a>name</a> attribute MUST return the server-specified metric-name.
+  The <a>name</a> attribute MUST return the DOMString value of the server-specified metric name.
 
   ### <dfn>duration</dfn> attribute
-  The <a>duration</a> attribute MUST return a double that contains the server-specified metric-value, or value `0.0`.
+  The <a>duration</a> attribute MUST return a double that contains the server-specified metric duration, or value `0.0`.
 
   ### <dfn>description</dfn> attribute
-  The <a>description</a> attribute MUST return the server-specified metric-description, or an empty string.
+  The <a>description</a> attribute MUST return the DOMString value of the server-specified metric description, or an empty string.
 </section>
 
 <!-- TODO: How do extend and cross-reference the interface? -->
@@ -162,9 +167,9 @@
   <li>For each server-specified metric received from parsing the <a>Server-Timing header field</a>, perform the following steps:
     <ol data-link-for="PerformanceServerTiming">
       <li>Let <dfn>entry</dfn> be a new <a>PerformanceServerTiming</a> object.</li>
-      <li>Set <a>name</a> to the server-specified metric-name.</li>
-      <li>Set <a>duration</a> to the server-specified metric-value, or value 0 if omitted or not representable as a double.</li>
-      <li>Set <a>description</a> to the server-specified metric-description, or an empty string.</li>
+      <li>Set <a>name</a> to metric-name.</li>
+      <li>Set <a>duration</a> to the server-timing-param-value for the server-timing-param where server-timing-param-name is case-insensitively equal to "duration", or value 0 if omitted or not representable as a double.</li>
+      <li>Set <a>description</a> to the server-timing-param-value for the server-timing-param where server-timing-param-name is case-insensitively equal to "description", or an empty string if omitted.</li>
       <li>Append <var>entry</var> to <var>entryList</var>.
       </li>
     </ol>
@@ -211,18 +216,18 @@
     > Host: example.com
 
     &lt; HTTP/1.1 200 OK
-    &lt; Server-Timing: miss, db=53, app=47.2;
-    &lt; Server-Timing: customView, dc;atl
+    &lt; Server-Timing: miss, db;duration=53, app;duration=47.2
+    &lt; Server-Timing: customView, dc;description=atl
     &lt; Trailer: Server-Timing
     &lt; (... snip response body ...)
-    &lt; Server-Timing: total=123.4
+    &lt; Server-Timing: total;duration=123.4
   </pre>
 
   <table class="parameters">
     <thead>
       <tr>
         <th>Name</th>
-        <th>Value</th>
+        <th>Duration</th>
         <th>Description</th>
       </tr>
     </thead>