Skip to content
Browse files

CH-DW > CH-RW (resource width) because "display" is an overloaded term

  • Loading branch information...
1 parent a1f8647 commit 1f9dcbf5017edfc6f68586925546431be8b12014 @igrigorik committed Oct 29, 2013
Showing with 25 additions and 25 deletions.
  1. +8 −8 README.md
  2. +17 −17 draft.md
View
16 README.md
@@ -2,7 +2,7 @@
Client Hints can be used as input to proactive content negotiation; just as the Accept header allowed clients to indicate what formats they prefer, Client Hints allow clients to indicate a list of device and agent specific preferences for the request resource.
-Client Hints can be used to automate negotiation of optimal resolution and size of delivered image assets to different clients. For example, given the following HTML markup:
+Client Hints can be used to automate negotiation of optimal resolution and size of delivered image resources to different clients. For example, given the following HTML markup:
```html
<img src="img.jpg" width="160" alt="I'm responsive!">
@@ -15,20 +15,20 @@ GET /img.jpg HTTP/1.1
User-Agent: Awesome Browser
Accept: image/webp, image/jpg
CH-DPR: 2.0
-CH-DW: 160
+CH-RW: 160
```
```http
HTTP/1.1 200 OK
Server: Awesome Server
Content-Type: image/jpg
Content-Length: 124523
-Vary: CH-DPR, CH-DW
+Vary: CH-DPR, CH-RW
DPR: 2.0
(image data)
```
-In above example, the client advertises its device pixel ratio (DPR) via `CH-DPR` header, and (optionally) the display width (in DIPs) of the requested asset. Given this information, the server is then able to dynamically select the optimal asset for the client, and confirms its selection via the `DPR` header.
+In above example, the client advertises its device pixel ratio (DPR) via `CH-DPR` header, and the resource display width via `CH-RW` (in DIPs) of the requested resource. Given this information, the server is then able to dynamically select the optimal resource for the client, and confirms its selection via the `DPR` header.
For full details on negotiation workflow, refer to the [spec](https://github.com/igrigorik/http-client-hints/blob/master/draft-grigorik-http-client-hints-01.txt).
@@ -59,19 +59,19 @@ CH-DPR automates resolution switching use-case and eliminates the need to write
<img src="pic.png"> (or) <img src-1="pic.png">
```
-CH-DW simplifies delivery of variable sized images: author specifies the breakpoints using src-N markup, the client computes the display width (in DIPs) of the image asset and sends it to the server. Given CH-DPR and CH-DW values, the server can then select the appropriate asset:
+CH-RW simplifies delivery of variable sized images: author specifies the breakpoints using src-N markup, the client computes the display width (in DIPs) of the image and sends it to the server. Given CH-DPR and CH-RW values, the server can then select the appropriate resource:
```html
<!-- src-N variable size + DPR selection -->
<img src-1="100% (30em) 50% (50em) calc(33% - 100px);
pic100.png 100, pic200.png 200, pic400.png 400,
pic800.png 800, pic1600.png 1600, pic3200.png 3200">
-<!-- equivalent functionality via CH-DPR + CH-DW (see HTTP exchange above) -->
+<!-- equivalent functionality via CH-DPR + CH-RW (see HTTP exchange above) -->
<img src-1="100% (30em) 50% (50em) calc(33% - 100px); pic.png">
```
-The combination of `CH-DPR` and `CH-DW` allows the server to deliver 'pixel perfect' assets that match the device resolution and the exact display size. However, note that the server is not required to do so - e.g. it can round / bin the advertised values based on own logic and serve the closest matching asset (just as src-N picks the best / nearest asset based on provided urls in the markup).
+The combination of `CH-DPR` and `CH-RW` allows the server to deliver 'pixel perfect' images that match the device resolution and the exact display size. However, note that the server is not required to do so - e.g. it can round / bin the advertised values based on own logic and serve the closest matching resource (just as src-N picks the best / nearest resource based on provided urls in the markup).
Finally, Client Hints also simplifies art-direction use case covered by src-N:
@@ -90,7 +90,7 @@ Finally, Client Hints also simplifies art-direction use case covered by src-N:
### Comparison to User-Agent & Cookie-based strategies
-User-Agent sniffing cannot reliably detect the device pixel resolution of many devices (e.g. different generation iOS devices all have the same User-Agent header). Further, User-Agent detection cannot account for dynamic changes in DPR (e.g. zoomed in viewport on desktop devices). Similarly, User-Agent detection cannot tell us anything about the display width of the requested asset. In short, UA sniffing does not work.
+User-Agent sniffing cannot reliably detect the device pixel resolution of many devices (e.g. different generation iOS devices all have the same User-Agent header). Further, User-Agent detection cannot account for dynamic changes in DPR (e.g. zoomed in viewport on desktop devices). Similarly, User-Agent detection cannot tell us anything about the resource display width of the requested resource. In short, UA sniffing does not work.
HTTP Cookies can be used to [approximate CH behavior](https://github.com/jonathantneal/http-client-hints), but are subject to many limitations: client hints are not available on first request (missing cookie) or for any client who has cleared or disabled cookies; cookies impose additional client-side latency by requiring JavaScript execution to create and manage cookies; cookie solutions are limited to same-origin requests; cookie solutions are not HTTP cache friendly (cannot Vary on Cookie).
View
34 draft.md
@@ -111,9 +111,9 @@ This document defines the following hints:
- Description: Device Pixel Ratio (DPR), is the ratio between physical pixels and density independent pixels on the device.
- Value Type: number
-### CH-DW
+### CH-RW
-- Description: display width of the requested resource in density independent pixels on the device.
+- Description: Resource Width (RW), is the display width of the requested resource in density independent pixels on the device.
- Value Type: number
@@ -126,12 +126,12 @@ This document defines the following confirmation headers:
### DPR
-- Description: ratio between physical pixels and density independent pixels of the selected asset.
+- Description: ratio between physical pixels and density independent pixels of the selected resource.
- Value Type: number
-DPR ratio affects the calculation of intrinsic size of the image on the client (i.e. typically, the client automatically scales the natural size of the image by the DPR ratio to derive its display dimensions). As a result, the server must explicitly indicate the DPR of the asset whenever CH-DPR hint is used, and the client must use the DPR value returned by the server to perform its calculations. In case the server returned DPR value contradicts previous client-side DPR indication (e.g. srcN's x-viewport), the server returned value must take precedence.
+DPR ratio affects the calculation of intrinsic size of the image on the client (i.e. typically, the client automatically scales the natural size of the image by the DPR ratio to derive its display dimensions). As a result, the server must explicitly indicate the DPR of the resource whenever CH-DPR hint is used, and the client must use the DPR value returned by the server to perform its calculations. In case the server returned DPR value contradicts previous client-side DPR indication (e.g. srcN's x-viewport), the server returned value must take precedence.
-The server does not need to confirm display width selection as this value can be derived from the asset itself once it is decoded by the client.
+The server does not need to confirm resource width selection as this value can be derived from the resource itself once it is decoded by the client.
Examples
@@ -141,18 +141,18 @@ For example, given the following request header:
~~~
CH-DPR: 2.0
- CH-DW: 160
+ CH-RW: 160
~~~
The server knows that the device pixel ratio is 2.0, and that the intended display width of requested resource is 160px, as measured by density independent pixels on the device.
-If the server uses above hints to perform resource selection, it must confirm its selection via the DPR response header to allow the client to calculate the appropriate intrinsic size of the image asset. The server does not need to confirm display width, only the ratio between physical pixels and density independent pixels of the selected image asset:
+If the server uses above hints to perform resource selection, it must confirm its selection via the DPR response header to allow the client to calculate the appropriate intrinsic size of the image resource. The server does not need to confirm resource width, only the ratio between physical pixels and density independent pixels of the selected image resource:
~~~
DPR: 1.0
~~~
-The DPR response header indicates to the client that the server has selected an asset with DPR ratio of 1.0. The client may use this information to perform additional processing on the resource - for example, calculate the appropriate intrinsic size of the image asset such that it is displayed at the correct resolution.
+The DPR response header indicates to the client that the server has selected resource with DPR ratio of 1.0. The client may use this information to perform additional processing on the resource - for example, calculate the appropriate intrinsic size of the image resource such that it is displayed at the correct resolution.
Opt-in mechanism
@@ -163,10 +163,10 @@ CH is an optional header which may be sent by the client when making a request t
For example, the server may advertise its support via Accept-CH header or an equivalent HTML meta element with http-equiv attribute:
~~~
- Accept-CH: DPR, DW
+ Accept-CH: DPR, RW
~~~
-When the client receives the opt-in signal indicating support for Client Hint adaptation, it should append the Client Hint headers that match the advertised field-values. For example, based on Accept-CH example above, the client may append CH-DPR and CH-DW headers to subsequent requests.
+When the client receives the opt-in signal indicating support for Client Hint adaptation, it should append the Client Hint headers that match the advertised field-values. For example, based on Accept-CH example above, the client may append CH-DPR and CH-RW headers to subsequent requests.
Interaction with Caches
@@ -178,13 +178,13 @@ Client Hints may be combined with Key ({{I-D.fielding-http-key}}) to enable fine
Key: CH-DPR;r=[1.5:]
~~~
-Above examples indicates that the cache key should be based on the CH-DPR header, and the asset should be cached and made available for any client whose device pixel ratio is 1.5, or higher.
+Above examples indicates that the cache key should be based on the CH-DPR header, and the resource should be cached and made available for any client whose device pixel ratio is 1.5, or higher.
~~~
- Key: CH-DW;r=[320:640]
+ Key: CH-RW;r=[320:640]
~~~
-Above example indicates that the cache key should be based on the CH-DW header, and the asset should be cached and made available for any asset whose display width falls between 320 and 640px.
+Above example indicates that the cache key should be based on the CH-RW header, and the resouce should be cached and made available for any request whose display width falls between 320 and 640px.
In absence of support for fine-grained control of the cache key via the Key header field, Vary response header can be used to indicate that served resource has been adapted based on specified Client Hint preferences.
@@ -195,10 +195,10 @@ In absence of support for fine-grained control of the cache key via the Key head
Above example indicates that the cache key should be based on the CH-DPR header.
~~~
- Vary: CH-DPR, CH-DW
+ Vary: CH-DPR, CH-RW
~~~
-Above example indicates that the cache key should be based on the CH-DPR and CH-DW headers.
+Above example indicates that the cache key should be based on the CH-DPR and CH-RW headers.
Relationship to the User-Agent Request Header
@@ -213,7 +213,7 @@ IANA Considerations
The Client Hints Request Header Field
-------------------------------------
-This document defines the "CH-DPR", "CH-DW", and "DPR" HTTP request fields, and registers it in the Permanent Message Headers registry.
+This document defines the "CH-DPR", "CH-RW", and "DPR" HTTP request fields, and registers it in the Permanent Message Headers registry.
- Header field name: CH-DPR
- Applicable protocol: HTTP
@@ -222,7 +222,7 @@ This document defines the "CH-DPR", "CH-DW", and "DPR" HTTP request fields, and
- Specification document(s): [this document]
- Related information: for Client Hints
-- Header field name: CH-DW
+- Header field name: CH-RW
- Applicable protocol: HTTP
- Status: Informational
- Author/Change controller: Ilya Grigorik, ilya@igvita.com

0 comments on commit 1f9dcbf

Please sign in to comment.
Something went wrong with that request. Please try again.