Skip to content

Commit

Permalink
Add a User-Agent String section (#166)
Browse files Browse the repository at this point in the history 
* Editorial: Remove "non-standard" from abstract.

Also, get rid of an old issue that seems less relevant.

Fixes: #165

* Editorial: Rework introduction

ref. #146

* Editorial: Add Karl Dubost to acknowledgements.

Plus some whitespace cleanup.

* Add a User-Agent String section.

Fixes #146

* Editorial: Fix forless media features

Also do some line wrapping.

See: speced/bikeshed#2200

* Add in @karlcow's suggestions

Co-authored-by: Karl Dubost <[email protected]>
  • Loading branch information
@miketaylr @karlcow
miketaylr and karlcow authored Feb 1, 2022
1 parent 07c590e commit 3ca5920
Showing 1 changed file with 199 additions and 16 deletions.
215 changes: 199 additions & 16 deletions compatibility.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ H1: Compatibility
Shortname: compat
Text Macro: TWITTER compatstandard
Text Macro: LATESTRD 2021-12
Abstract: This standard describes a collection of non-standard (and often vendor-prefixed) CSS properties and DOM APIs that web browsers need to support for compatibility with the de facto web.
Abstract: This standard describes a collection of web platform features that web browsers need to support for compatibility with the de facto web.
Translation: ja https://triple-underscore.github.io/compat-ja.html
Indent: 2
Markup Shorthands: dfn yes
Expand Down Expand Up @@ -47,11 +47,22 @@ urlPrefix: https://drafts.csswg.org/css-values-3/
text: dppx; url: #dppx
</pre>

<pre class="biblio">
{
"HTTP-SEMANTICS": {
"href": "https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html",
"title": "HTTP Semantics",
"authors": [ "R. Fielding", "M. Nottingham", "J. Reschke" ]
}
}
</pre>

<pre class=link-defaults>
spec:css-display-3; type:value; for:display; text:flex
spec:css-flexbox-1; type:value; text:inline-flex
spec:filter-effects-1; type:property; text:filter
spec:css-conditional-3; type:at-rule; text:@media
spec:infra; type:dfn; text:user agent
</pre>

<!-- Commented out until we know what the heck to put here:
Expand All @@ -60,13 +71,15 @@ spec:css-conditional-3; type:at-rule; text:@media
<h2 id='introduction'>Introduction</h2>
<em>This section is non-normative.</em>

There exists an increasingly large corpus of web content that depends on web browsers supporting a number of <code>webkit</code>-prefixed CSS properties and DOM APIs for functionality or layout. This holds especially true for mobile-optimized web content.
There exists an increasingly large corpus of web content that depends on web browsers supporting a
number of specific vendor CSS properties and DOM APIs for functionality or layout.
This holds especially true for mobile-optimized web content, which is highly dependent on <code>webkit</code>-prefixed properties.

This specification aims to describe the minimal set of <code>webkit</code>-prefixed CSS properties and DOM APIs that user agents are required to support for web compatibility.
This specification aims to describe the minimal set of <code>webkit</code>-prefixed CSS properties
and DOM APIs that user agents are required to support for web compatibility, which aren't
specified elsewhere.

<div class="XXX">
The <a href="https://wiki.mozilla.org/Compatibility/Mobile/Non_Standard_Compatibility">Non-Standard Compatibility</a> wiki page will serve as a rough guide for what this specification intends to cover.
</div>
The HTTP <code>User-Agent</code> header field as found in major browsers today is also described.

<h2 id='conformance'>Conformance</h2>
All diagrams, examples, and notes in this specification are
Expand Down Expand Up @@ -115,19 +128,22 @@ The following <code>-webkit-</code> <a>vendor prefixed</a> at-rules must be supp
<h3 id="css-media-queries">CSS Media Queries</h3>

<h4 id="css-media-queries-webkit-device-pixel-ratio">
<code>'-webkit-device-pixel-ratio'</code>
<code>'@media/-webkit-device-pixel-ratio'</code>
</h4>

<pre class='descdef mq'>
Name: -webkit-device-pixel-ratio
Name: '@media/-webkit-device-pixel-ratio'
Value: <<number>>
For: @media
Type: range
</pre>

<code>'-webkit-device-pixel-ratio'</code> must be treated as an alias of the <code><a>resolution</a></code> range type <a>media feature</a>, with its value interpreted as a <a>dppx</a> unit.
<code>'@media/-webkit-device-pixel-ratio'</code> must be treated as an alias of the
<code><a>resolution</a></code> range type <a>media feature</a>, with its value interpreted as a
<a>dppx</a> unit.

The <code>min-</code> or <code>max-</code> <a>prefixes on range features</a> must not apply to <code>'-webkit-device-pixel-ratio'</code>, instead the following aliases must be used:
The <code>min-</code> or <code>max-</code> <a>prefixes on range features</a> must not apply to
<code>'@media/-webkit-device-pixel-ratio'</code>, instead the following aliases must be used:

<table>
<thead>
Expand All @@ -149,17 +165,18 @@ The <code>min-</code> or <code>max-</code> <a>prefixes on range features</a> mus
</table>

<h4 id="css-media-queries-webkit-transform-3d">
<code>'-webkit-transform-3d'</code>
<code>'@media/-webkit-transform-3d'</code>
</h4>

<pre class='descdef mq'>
Name: -webkit-transform-3d
Name: '@media/-webkit-transform-3d'
Value: <<mq-boolean>>
For: @media
Accepts min/max prefixes: no
</pre>

The <code>'-webkit-transform-3d'</code> media feature is used to query whether the user agent supports CSS 3D transforms. [[css-transforms-1]]
The <code>'@media/-webkit-transform-3d'</code> <a>media feature</a> is used to query whether the
user agent supports CSS 3D transforms. [[css-transforms-1]]

If the user agent supports 3D transforms, the value will be 1. Otherwise the value is 0.

Expand Down Expand Up @@ -814,12 +831,178 @@ The following are the event handlers and their corresponding event handler event
WebKit also has this on <a href="https://github.com/WebKit/webkit/blob/e455672f9e6861ced85d8be01cb7bc03a30a0555/LayoutTests/fast/dom/event-handler-attributes.html#L335">HTMLFrameSetElement</a>. It's unclear if this is needed for compatibility.
</div>

<h2 id="ua-string-section">The User-Agent String</h2>

The <code>User-Agent</code> header field syntax is formally defined by [[!HTTP-SEMANTICS]] and
provides SHOULD-level guidance on its value. This section serves as a descriptive record of the
<code>User-Agent</code> patterns found in the so-called major web browsers, but much of it will
apply to other browsers with a shared heritage (i.e., forks and embedders) as well as any
<a>user agent</a> in the more general sense that send a <code>User-Agent</code> <a>header</a>.

<h3 id="ua-string-patterns">User-Agent Tokens</h3>

A User-Agent <dfn>token</dfn> is a string that represents an abstraction over a semantic unit in the
<code>User-Agent</code> string. This document formalizes <a>tokens</a> as a <a>string</a> that
begins with an opening bracket "<" and ends with a closing ">" bracket, e.g.,
<code>&lt;version&gt;</code>.

<h4 id="ua-string-token-reference">User-Agent Token Reference</h4>

This is a non-exhaustive list of common User-Agent <a>tokens</a>.

<table>
<thead>
<th>Tokens</th>
<th>Description</th>
</thead>
<tbody>
<!-- TODO(miketaylr): fit Android into existing model
<tr>
<td><code>&lt;<dfn>androidVersion</dfn>&gt;</code></td>
<td>Represents Android major version.</td>
</tr> -->
<tr>
<td><code>&lt;<dfn>deviceCompat</dfn>&gt;</code></td>
<td>Represents the form-factor of the device. Primarily this is <code>Mobile </code>, or just
the empty string, for Desktop or non-mobile devices. Some browsers have also sent token values
such as <code>Tablet</code>, <code>TV</code>, <code>Mobile VR</code>, etc., or included
build information as well.</td>
</tr>
<!-- TODO(miketaylr): fit Android into existing model
<tr>
<td><code>&lt;<dfn>deviceModel</dfn>&gt;</code></td>
<td>Represents Android device model.</td>
</tr>
-->
<tr>
<td><code>&lt;<dfn>frozenWebKitVersion</dfn>&gt;</code></td>
<td><code>AppleWebKit/</code> followed by a WebKit revision number, (<code>537.36</code> in
the case of Chrome, and <code>605.1.15</code> in the case of Safari), followed by
<code> (KHTML, like Gecko)</code>.</td>
</tr>
<tr>
<td><code>&lt;<dfn>frozenSafariVersion</dfn>&gt;</code></td>
<td><code>Safari/</code> followed by a WebKit revision number, (<code>537.36</code> in
the case of Chrome, and <code>605.1.15</code> in the case of Safari).</td>
</tr>
<tr>
<td><code>&lt;<dfn>legacyMozillaVersion</dfn>&gt;</code></td>
<td><code>Mozilla/5.0</code> was added by Konqueror in their user agent string to make sure they were served the right content. It then became part of the normal string parser would expect when processing a user agent string.</td>
</tr>
<tr>
<td><code>&lt;<dfn>majorVersion</dfn>&gt;</code></td>
<td>Represents the browser's major version number.</td>
</tr>
<tr>
<td><code>&lt;<dfn>minorVersion</dfn>&gt;</code></td>
<td>Represents the browser's non-major version numbers.</td>
</tr>
<tr>
<td><code>&lt;<dfn>oscpu</dfn>&gt;</code></td>
<td>Represents the device operating system and (optionally) CPU architecture.</td>
</tr>
<tr>
<td><code>&lt;<dfn>platform</dfn>&gt;</code></td>
<td>Represents the underlying device platform.
</tr>
</tbody>
</table>

<h3 id="ua-string-meta-structure">Meta Structure</h3>

The User-Agent strings that follow share the common meta structure:

<code>&lt;<a>legacyMozillaVersion</a>&gt;</code> (<code>a</code>) <code>b</code>

Where <code>a</code> is a set of tokens representing device information and <code>b</code> is a set
of tokens representing browser information.

<h3 id="ua-string-chrome">Chrome</h3>

<h4 id="ua-string-pattern-chrome">Chrome User-Agent pattern</h4>

<code>&lt;<a>legacyMozillaVersion</a>&gt; (&lt;<a>platform</a>&gt;; &lt;<a>oscpu</a>&gt;)
&lt;<a>frozenWebKitVersion</a>&gt; Chrome/&lt;<a>chromeVersion</a>&gt; &lt;<a>deviceCompat</a>&gt;
&lt;<a>frozenSafariVersion</a>&gt;</code>

<div class="example" id="chrome-ua-examples">
<strong>Desktop</strong>: <code>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.36</code>

<strong>Mobile</strong>: <code>Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36 (KHTML,
like Gecko) Chrome/96.0.4664.93 Mobile Safari/537.36</code>
</div>

<h4 id="ua-string-tokens-chrome">Chrome-specific tokens</h4>

<code>&lt;<dfn>chromeVersion</dfn>&gt;</code> decomposes to the following:
<!-- TODO(miketaylr): add dfn for "decompose -->

<code>&lt;<a>majorVersion</a>&gt;.&lt;<a>minorVersion</a>&gt;</code>, where
<code>&lt;<a>minorVersion</a>&gt;</code> represents MINOR.BUILD.PATCH version numbers.

<h3 id="ua-string-firefox">Firefox</h3>

<h4 id="ua-string-pattern-firefox">Firefox User-Agent pattern</h4>

<code>&lt;<a>legacyMozillaVersion</a>&gt; (&lt;<a>platform</a>&gt;; &lt;<a>oscpu</a>&gt; rv:&lt;
<a>firefoxVersion</a>&gt;) Gecko/&lt;<a>geckoVersion</a>&gt; Firefox/&lt;<a>firefoxVersion</a>&gt;</code>

<div class="example" id="firefox-ua-examples">
<strong>Desktop</strong>: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:100.0) Gecko/20100101
Firefox/100.0</code>

<strong>Mobile</strong>: <code>Mozilla/5.0 (Android 10; Mobile; rv:100.0) Gecko/100.0
Firefox/100.0</code>
</div>

<h4 id="ua-string-tokens-firefox">Firefox-specific tokens</h4>

<code>&lt;<dfn>firefoxVersion</dfn>&gt;</code> decomposes to the following:

<code>&lt;<a>majorVersion</a>&gt;.0</code>

In Firefox on desktop platforms (Windows, macOS, Linux, etc.),
<code>&lt;<dfn>geckoVersion</dfn>&gt;</code> is the frozen build
date "<code>20100101</code>". In Firefox on Android, <code>&lt;<a>geckoVersion</a>&gt;</code> is the
same value as <code>&lt;<a>firefoxVersion</a>&gt;</code>.


<h3 id="ua-string-safari">Safari</h3>

<h4 id="ua-string-pattern-safari">Safari User-Agent pattern</h4>

<code>&lt;<a>legacyMozillaVersion</a>&gt; (Macintosh; Intel Mac OS X 10_15_7)
&lt;<a>frozenWebKitVersion</a>&gt; Version/&lt;<a>safariVersion</a>&gt; &lt;<a>deviceCompat</a>&gt;
&lt;<a>frozenSafariVersion</a>&gt;</code>

<div class="example" id="safari-ua-examples">
<strong>Desktop</strong>: <code>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.36</code>

<strong>Mobile</strong>: <code>Mozilla/5.0 (iPhone; CPU iPhone OS 15_3 like Mac OS X)
AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.2 Mobile/15E148 Safari/604.1
</code>
</div>

<h4 id="ua-string-tokens-safari">Safari-specific tokens</h4>

<code>&lt;<dfn>safariVersion</dfn>&gt;</code> decomposes to the following:

<code>&lt;<a>majorVersion</a>&gt;.&lt;<a>minorVersion</a>&gt;</code>, where
<code>&lt;<a>minorVersion</a>&gt;</code> is a single digit.

<h2 id="acknowledgements" class="no-num">Acknowledgements</h2>
Thanks to Alan Cutter, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, Daniel Holbert, David Håsäther, Domenic Denicola, hexalys, Jean-Yves Perrier, Jacob Rossi, Philip Jägenstedt, Rick Byers, Simon Pieters, Stanley Stuart, William Chen and Your Name Here for feedback and contributions to this standard.
Thanks to Alan Cutter, Cameron McCormack, Chris Rebert, Chun-Min (Jeremy) Chen, Daniel Holbert,
David Håsäther, Domenic Denicola, hexalys, Jean-Yves Perrier, Jacob Rossi, Karl Dubost,
Philip Jägenstedt, Rick Byers, Simon Pieters, Stanley Stuart, William Chen and Your Name Here for
feedback and contributions to this standard.

Thanks to Mounir Lamouri and Marcos Cáceres for defining the {{ScreenOrientation}} interface. [[!screen-orientation]]
Thanks to Mounir Lamouri and Marcos Cáceres for defining the {{ScreenOrientation}} interface.
[[!screen-orientation]]

Special thanks to Apple and the WebKit.org blog authors for providing initial descriptions of much of the content defined in this specification.
Special thanks to Apple and the WebKit.org blog authors for providing initial descriptions of much
of the content defined in this specification.

This standard is written by
<a href="https://miketaylr.com/">Mike Taylor</a>
Expand Down

0 comments on commit 3ca5920

Please sign in to comment.