committing some of the rewrite based on feedback from TPAC; still have a lot to do.
authorJames Craig <jcraig@apple.com>
Tue, 17 Dec 2013 17:42:52 -0800
changeset 162 e343c00c58c6
parent 161 356bed431f91
child 163 76a207235379
committing some of the rewrite based on feedback from TPAC; still have a lot to do.
src/indie-ui-context.html
src/js/respec-transformers.js
src/obsolete/key-value-context.html
--- a/src/indie-ui-context.html	Tue Dec 17 11:34:31 2013 -0500
+++ b/src/indie-ui-context.html	Tue Dec 17 17:42:52 2013 -0800
@@ -96,133 +96,208 @@
 		</section>
 		
 		<!-- :::::::::::::::::::: INTRO :::::::::::::::::::: -->
-		<section id="intro" class="introductory informative">
+		<section id="intro" class="informative">
 			<h2>Introduction</h2>
 			<p>The primary goal of IndieUI User Context is to provide authorized web applications access to information about a user's relevant settings and preferences, to provide the best possible user experience to all users. Some complex web applications can provide a much better experience if given access to information such as a user's preferred color, font, screen, and even *restricted* assistive technology settings such as a preference to render captions, or whether a screen reader is on. General web pages developed using best practices may never need access to restricted user settings, but complex web applications can utilize this information to enhance the performance and user interface.</p>
 			<p>There are obviously major privacy implications to providing any user-specific information to a third-party such as a web site, so a critical part of this specification defines how user agents and web browsers must prevent unauthorized access to user information, including methods to prevent access from parties interested in abusive uses such as user "fingerprinting" by marketers. The IndieUI Working Group members believe we've solved this problem by preventing web sites from being able to detect any difference between a user preference that is <em>Off</em>, and a user preference that is <em>On</em> but is not shared with the requesting site.</p>
-			<p>The specification below adds several new "Media Features" to detect user settings, using existing syntax defined in the CSS3 Media Queries specification, and provides an access control extension to the MediaQueryList interface defined in the CSSOM View Model. Because this approach relies so heavily on features that overlap with work maintained by the CSS Working Group and Web Applications Working Group, it is likely that portions or all of this specification may move under the purview these other groups. At a minimum, the IndieUI Working Group requests guidance and a collaborative working relationship with CSS and WebApps.</p>
+			<p>This section defines feature keys for user settings for use with the UserSettings interface. Some keys can also be accessed as Media Features using syntax defined in the CSS Media Queries specification. User Agents SHOULD implement an access control mechanism that allows users to restrict access to senesitive information requested via the <code>userSettings()</code> or <code>matchMedia()</code> methods of the Window interface, or from the @media selector in CSS.
+
+			The specification below defines feature keys for user settings that can be requested through a new extension to the Window interface. Some keys can also be accessed as new "Media Features" to detect user settings, using existing syntax defined in the CSS Media Queries specification. Because this approach relies so heavily on features that overlap with work maintained by the CSS Working Group and Web Applications Working Group, it is possible that portions or all of this specification may move under the purview these other groups. At a minimum, the IndieUI Working Group requests guidance and a collaborative working relationship with CSS and WebApps.</p>
 			<p class="todo">
 				Todo: Move these to the refs section and link them here: <br>
-				http://www.w3.org/TR/css3-mediaqueries/<br>
-				http://www.w3.org/TR/cssom-view/#the-mediaquerylist-interface
+				http://www.w3.org/TR/css3-mediaqueries/
 			</p>
 		</section>
 		<!-- :::::::::::::::::::: END INTRO :::::::::::::::::::: -->
-		
-		<!-- :::::::::::::::::::: MediaQueryList :::::::::::::::::::: -->
-		<section>
-			<h2>Privacy Model</h2>
-			<p class="todo">Todo: Explain how the privacy model works: when user prompted, matchMedia returns false immediately, and only provides the updated match ansynchronously through matchMedia().addEventListener or subsequent requests to matchMedia().matches (e.g. on page reload) so there is never any detectable difference between "No" and "You don't need to know." A restricted @media block never prompts unless both the @media block and an included selector matches.</p>
-			<p class="todo">Todo: Add justification interface on a per-category setting (possibly meta tag or a partial interface on document). Justification string may be defined by an new JavaScript interface, or perhaps by a meta tag in the document head, such as:<br><code class="html" data-transform="syntaxMarkup">&lt;meta name="userMediaSettings" content="Used to enable captions and display them in your preferred font size and color."&gt;</code></p>
-
-
-			<section id="MediaQueryListExtensions">
-				<h4>Extensions to MediaQueryList</h4>
-
-				<section id="MediaQueryList-idl">
-					<h5>Partial Interface for MediaQueryList (IDL)</h5>
-					<dl title="partial interface MediaQueryList" class="idl">
-						
-						<dt>readonly attribute MediaQueryRestrictionType restriction</dt>
-						<dd>Returns the strictest MediaQueryRestrictionType defined in the user's settings for each MediaQueryRestrictionCategory matched by the current MediaQueryList. Defaults to <code>none</code>.
-						<p class="ednote">It's possible this property doesn't need to be in the IDL interface, as it may end up being a user agent implementation detail. There's probably no need for web authors to know how restricted a setting group is. They only need to know the setting value if the user has shared this information.</p>
-						</dd>
-
-						<dt>readonly attribute MediaQueryRestrictionCategory category</dt>
-						<dd><p class="ednote">Probably need to make this an array with multiple values, since you could have a media query that matched multiple restriction categories. e.g. <code>(subtitles) and (screenreader)</code> would match both <code>userMediaSettings</code> and <code>userScreenReaderSettings</code>.</p></dd>
-
-					</dl>
-				</section>
-
-				<p>To avoid privacy concerns and abusive uses such fingerprinting, User Agents MUST <em>immediately</em> match the default value of the media query for any restricted features that will result in a user prompt. If and when the user chooses to share settings from the relevant category with the requesting page, the web page author can receive a mediaQueryListChanged event, and make a subsequent request of the <code>matches</code> property of the MediaQueryList.</p>
-
-				<section class="informative">
-					<h4>Example restricted call to matchMedia</h4>
-					<p>The following example illustrates the code path that is executed when a user with a preference for audio descriptions visits a web page that uses window.matchMedia to enable the audio description track at load time.</p>
-					<pre class="example javascript" data-transform="syntaxJavaScript">
-						// Author defines a media query list to determine if the user wants descriptive audio.
-						var audioDescriptionQuery = window.matchMedia('(audio-description)');
 
-						// and defines and function to handle changes of this setting.
-						function handleAudioDescriptionChanged(mql) {
-						    if (mql.matches) {
-						        // User has shared that audio descriptions should be presented.
-						        // Enable the "descriptive audio" track in the video. 
-						    } else {
-						        // Set to default. Audio descriptions are off, 
-						        // or the user has chosen to not share this setting.
-						    }
-						}
-
-						/*
-						When the author first attempts to check the 'matches' property of the query, the user
-						agent will determine that this is a restricted setting, and immediately return false,
-						so the first call to this function on the initial page load will never result in
-						audio descriptions being enabled.
-
-						Note: The immediate return is critical to prevent blocking threads, as well as
-						eliminating potential abuse by fingerprinting scripts attempting to determine 
-						uniqueness using execution time of the synchronous call to mql.matches.
-						*/
-						
-						handleAudioDescriptionChanged(audioDescriptionQuery);
+		<!-- :::::::::::::::::::: Window Interface :::::::::::::::::::: -->
+		<section id="UserSettings">
+			<h3>Extension to the Window Interface</h3>
+			<dl title="partial interface Window" class="idl">
 
-						/*
-						However, at the same time, the user will be prompted to decide whether or not to share 
-						their media alternative settings with the requesting web site. 
-
-						The web author can register for a change listener on this media query list, and the event
-						handler will be called asynchronously when the user agrees to share their media settings.
-						*/
-
-						audioDescriptionQuery.addListener(handleAudioDescriptionChanged);
-
-						// Note: Subsequent page loads should not cause the user to be prompted again.
+				<dt>DOMstring? userSetting()</dt>
+				<dd>
+					<p class="ednote">Description TBD (esp re: privacy and fingerprinting, and prompt access for certain parameters on a per-domain basis, similar to location sharing)</p>
+					
+					<pre class="example" data-transform="syntaxJavaScript">
+						// example of preferences defined within the IndieUI User Context specification.
+						window.userSetting('fontSize'); // e.g. '16px'
+						window.userSetting('subtitles'); // e.g. returns 'display' if the user wants to see subtitles/captions; otherwise returns 'none'
+						
+						// example of an taxonomy- or vendor-prefixed settings proposals, intended for standardization.
+						window.userSetting('webkitFoo');
+						window.userSetting('mozFoo');
+						
+					</pre>
+					<dl class="parameters">
+						
+						<dt>DOMString setting</dt>
+						<dd>Identifying key for the preference value to be returned. User Agents MAY support prefixed keys for vendor-proposed or implementation-specific settings, or another external taxonomy.</dd>
+					</dl>
+				</dd>
+				<dt>void addUserSettingListener()</dt>
+				<dd>
+					<dl class="parameters">
+						<dt>DOMString setting</dt><dd></dd>
+						<dt>UserSettingListener callback</dt><dd></dd>
+					</dl>
+				</dd>
+				<dt>void removeUserSettingListener()</dt>
+				<dd>
+					<dl class="parameters">
+						<dt>DOMString setting</dt><dd></dd>
+						<dt>UserSettingListener callback</dt><dd></dd>
+					</dl>
+				</dd>
 
-					</pre>
-				</section>
-
-			</section>
+			</dl>
+			<p class="note">Standard vendor prefixes (<code>ie</code>, <code>moz</code>, <code>o</code>, <code>webkit</code>) are reserved, and any additional implementation or external taxonomy identifiers may be defined in a supplemental, informative document.</p>
 
-			<section id="MediaQueryRestrictionCategory">
-				<h4>Enumeration MediaQueryRestrictionCategory</h4>
-				<dl title="enum MediaQueryRestrictionCategory" class="idl">
-					<dt>none</dt><dd>No category defined.</dd>
-					<dt>userColors</dt><dd>User settings related to color preferences. No default restriction.</dd>
-					<dt>userFonts</dt><dd>User settings related to type and font preferences. No default restriction.</dd>
-					<dt>userMediaSettings</dt><dd>User settings related to media alternatives such as captions/subtitles, audio description, etc. Default restriction is to prompt the user for permission.</dd>
-					<dt>userScreenReaderSettings</dt><dd>User settings related to screen readers. Default restriction is to prompt the user with a justification provided by the requesting web site.</dd>
+		</section>
+		<!-- :::::::::::::::::::: END Window Interface :::::::::::::::::::: -->
+
+		<!-- :::::::::::::::::::: UserSettingListener :::::::::::::::::::: -->
+		<section id="UserSettingListener">
+			<h4>UserSettingListener Callback Interface</h4>
+			<dl title="callback interface UserSettingListener" class="idl">
+				<dt>void handleUserSettingChanged()</dt>
+				<dd>
+					<dl class="parameters">
+						<dt>DOMString setting</dt><dd></dd>
+						<dt>optional DOMString? value</dt><dd></dd>
+						<dt>optional DOMString? previousValue</dt><dd></dd>
+					</dl>
+				</dd>
+			</pre>
+
+		</section>
+		<!-- :::::::::::::::::::: END UserSettingListener :::::::::::::::::::: -->
+
+		<!-- :::::::::::::::::::: MediaQueryList :::::::::::::::::::: -->
+		<section id="MediaQueryListExtensions">
+			<h4>Extension to the MediaQueryList Interface</h4>
+			<p class="ednote">It is likely that this will be an implementation detail, rather than something that needs to be specified as an IDL extension to MQL.</p>
+			<section id="MediaQueryList-idl">
+				<h5>Partial Interface for MediaQueryList (IDL)</h5>
+				<dl title="partial interface MediaQueryList" class="idl">
+					
+					<dt>readonly attribute RestrictionCategory[] categories</dt>
+					<dd>One or more matched restriction categories. e.g. <code>(subtitles) and (screenreader)</code> would match both <code>userMediaSettings</code> and <code>userScreenReaderSettings</code>.</dd>
+
 				</dl>
 			</section>
 
-			<section id="MediaQueryRestrictionType">
-				<h4>Enumeration MediaQueryRestrictionType</h4>
-				<dl title="enum MediaQueryRestrictionType" class="idl">
-					<dt>none</dt><dd>No restriction. Default for most media queries.</dd>
-					<dt>prompt</dt><dd>Prompt the user. Justification string is optional.</dd>
-					<dt>justification</dt><dd>Prompt the user with a required justification string provided by the requesting web page.</dd>
-					<dt>disallow</dt><dd>Not the default for any category, but a user agent may allow the used to choose to always disallow certain settings across-the-board or on a per-site basis.</dd>
+			<p>To avoid privacy concerns and abusive uses such as fingerprinting, User Agents MUST <em>immediately</em> match the default value of the media query for any restricted features that will result in a user prompt. If and when the user chooses to share settings from the relevant category with the requesting page, the web page author can receive a mediaQueryListChanged event, and make a subsequent request of the <code>matches</code> property of the MediaQueryList.</p>
+
+
+		</section>
+		<!-- :::::::::::::::::::: END MediaQueryList :::::::::::::::::::: -->
+
+		<!-- :::::::::::::::::::: Privacy Model :::::::::::::::::::: -->
+		<section>
+			<h2>Privacy Model</h2>
+			<p class="todo">Todo: Explain how the privacy model works: when user prompted, window.userSetting() or window.matchMedia() return the default value or null immediately, and only provides the updated match ansynchronously through matchMedia().addEventListener or on subsequent requests to matchMedia().matches (e.g. on page reload) so there is never any detectable difference between "No" and "You don't need to know." A restricted @media block never prompts unless both the @media block and an included selector matches.</p>
+			<p class="todo">Todo: Add justification interface on a per-category setting (possibly meta tag or a partial interface on document). Justification string may be defined by an new JavaScript interface, or perhaps by a meta tag in the document head, such as:<br><code class="html" data-transform="syntaxMarkup">&lt;meta name="userMediaSettings" content="Used to enable captions and display them in your preferred font size and color."&gt;</code></p>
+		
+			<section id="RestrictionCategory">
+				<h4>Restriction Categories</h4>
+				<dl title="enum RestrictionCategory" class="idl">
+					<dt>none</dt><dd>No category defined (default value).</dd>
+					<dt>userColors</dt><dd>User settings related to color preferences. No default restriction.</dd>
+					<dt>userFonts</dt><dd>User settings related to type and font preferences. No default restriction.</dd>
+					<dt>userMediaSettings</dt><dd>User settings related to media alternatives such as captions/subtitles, audio description, etc. Default suggested restriction is to prompt the user for permission.</dd>
+					<dt>userScreenReaderSettings</dt><dd>User settings related to screen readers. Default restriction is to prompt the user with a justification provided by the requesting web site author.</dd>
 				</dl>
 			</section>
 
 			<section class="informative">
-				<h4>Example MediaQueryRestrictionType</h4>
+				<h4>Example Restriction</h4>
+				<p>In the following example, the web author attempts to query two restricted user settings using two different techniques. For the sake of the example, assume the user's setting do match the specified query.</p>
 				<pre class="example javascript" data-transform="syntaxJavaScript">
-					// Query matches if both audio descriptions and screen reader are enabled.
-					var mql = window.matchMedia('(audio-description) and (screenreader)');
+					// Query matches if both audio descriptions and screen reader are enabled
+					// and the user's privacy settings allow the match.
+					var mediaMatch = matchMedia('(audio-description) and (screenreader)').matches;
+
+					// The following is equivalent to the previous MQ approach, but uses the UserSettings interface.
+					var settingsMatch = (userSetting('audioDescription') &amp;&amp; userSetting('screenreader'));
+
+					if (mediaMatch || settingsMatch) {
+					  console.log('A screen reader is active and the user prefers audio descriptions.');
+					} else {
+					  console.log('The settings do not match, or the user has chosen to not share that information.');
+					}
+
 				</pre>
-				<p>In the previous example, <code>mql.restriction</code> will return <code>"justification"</code> because the matched categories are userMediaSettings (which has a default restriction of "prompt") and userScreenReaderSettings (which has the default restriction of "justification"). Since justification is more strict of the two restriction types, it is used.</p>
-				<p>However, if a user were to change their browser settings and allow all sites to access any media feature in the userScreenReaderSettings category without restriction, <code>mql.restriction</code> will return <code>"prompt"</code> because the matched categories are userMediaSettings (which has a default restriction of "prompt") and userScreenReaderSettings (which now has the user-overridden restriction of "none"). Since "prompt" is more strict of the two restriction types, it is used.</p>
+				<p>Depending on the user's privacy settings and implementation details of the user agent, there are a number of outcomes:</p>
+				<ul>
+					<li>If the user has previously allowed access for these settings, the Media Query will <em>match</em> the value immediately.</li>
+					<li>If the user has a general 'prompt' restriction for these settings, the Media Query will <em>not match</em> the value, and the user agent MAY prompt the user with a generic dialog similar to that for location sharing.</li>
+					<li>If the user requires a 'justification' restriction for these settings, the Media Query will <em>not match</em> the value, and the user agent MAY prompt the user with a dialog that includes the author-provided justification string.</li>
+					<li>If the user has disallowed access for these settings, the Media Query will never match the value.</li>
+				</ul>
+
+			</section>
+
+			<section class="informative">
+				<h4>Example restricted call to <code>window.userSettings()</code></h4>
+				<p>The following example illustrates the code path that is executed when a user with a preference for audio descriptions visits a web page that uses window.settings to enable the audio description track at load time.</p>
+				<p class="todo">Todo: Add code example.</p>
+			</section>
+
+			<section class="informative">
+				<h4>Example restricted call to <code>window.matchMedia()</code></h4>
+				<p>The following example illustrates the code path that is executed when a user with a preference for audio descriptions visits a web page that uses window.matchMedia to enable the audio description track at load time.</p>
+				<pre class="example javascript" data-transform="syntaxJavaScript">
+					// Author defines a media query list to determine if the user wants descriptive audio.
+					var audioDescriptionQuery = window.matchMedia('(audio-description)');
+
+					// and defines and function to handle changes of this setting.
+					function handleAudioDescriptionChanged(mql) {
+					    if (mql.matches) {
+					        // User has shared that audio descriptions should be presented.
+					        // Enable the "descriptive audio" track in the video. 
+					    } else {
+					        // Set to default. Audio descriptions are off, 
+					        // or the user has chosen to not share this setting.
+					    }
+					}
+
+					/*
+					When the author first attempts to check the 'matches' property of the query, the user
+					agent will determine that this is a restricted setting, and immediately return false,
+					so the first call to this function on the initial page load will never result in
+					audio descriptions being enabled.
+
+					Note: The immediate return is critical to prevent blocking threads, as well as
+					eliminating potential abuse by fingerprinting scripts attempting to determine 
+					uniqueness using execution time of the synchronous call to mql.matches.
+					*/
+					
+					handleAudioDescriptionChanged(audioDescriptionQuery);
+
+					/*
+					However, at the same time, the user will be prompted to decide whether or not to share 
+					their media alternative settings with the requesting web site. 
+
+					The web author can register for a change listener on this media query list, and the event
+					handler will be called asynchronously when the user agrees to share their media settings.
+					*/
+
+					audioDescriptionQuery.addListener(handleAudioDescriptionChanged);
+
+					// Note: Subsequent page loads should not cause the user to be prompted again.
+
+				</pre>
 			</section>
 
 		</section>
-		<!-- :::::::::::::::::::: END MediaQueryList :::::::::::::::::::: -->
+		<!-- :::::::::::::::::::: END Privacy Model :::::::::::::::::::: -->
 
-		<!-- :::::::::::::::::::: Media Features :::::::::::::::::::: -->
-		<section id="MediaFeatures">
-			<h2>Media Features</h2>
-			<p>This section defines media features using syntax defined in the CSS3 Media Queries specification, but adds a RestrictionCategory parameter used by the access control extension to the MediaQueryList interface and the @media selector. <span class="todo">Todo: link these the the relevant portions of the access control extension.</span></p>
-			<p>The media features are grouped by restriction categories (e.g. type settings, media settings, etc.) that define related media features, and recommended default restriction levels.</p>
+		<!-- :::::::::::::::::::: Settings and Media Features :::::::::::::::::::: -->
+		<section id="Settings">
+			<h2>Settings Keys and Related Media Feature counterparts</h2>
+			<p>This section defines feature keys for user settings for use with the UserSettings interface. Some keys can also be accessed as Media Features using syntax defined in the CSS Media Queries specification. User Agents SHOULD implement an access control mechanism that allows users to restrict access to senesitive information requested via the <code>userSettings()</code> or <code>matchMedia()</code> methods of the Window interface, or from the @media selector in CSS. <span class="todo">Todo: link these the the relevant portions of the access control extension.</span></p>
+			<p>The features are grouped by restriction categories (e.g. type settings, media settings, etc.) that define related media features and recommended default restriction levels.</p>
 
 			<!-- :::::::::::::::::::: userColors :::::::::::::::::::: -->
 			<section id="userColors" class="restriction-category">
@@ -230,16 +305,16 @@
 
 				<dl class="properties">
 					<dt>Restriction Category (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionCategory">userColors</dd>
-					<dt>Default Restriction Type (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionType">none</dd>
+					<dd data-transform="linkRestrictionCategory">userColors</dd>
+					<dt>Suggested User Agent Restriction</dt>
+					<dd>none</dd>
 				</dl>
 
 				<p class="note">Color settings are not be restricted by default from the requesting page, primarily because a site can figure out most of this information using some creative CSS and JavaScript. These keys are therefore primarily intended as convenience accessors so that web authors can more easily provide adaptive interfaces that work well for all users. The display inversion feature is not currently detectable, but does not represent a major concern for privacy or fingerprinting since it is unlikely that most individuals will have this setting enabled all the time.</p>
 				<p class="ednote">Note: A generalized equivalent to Microsoft's <a href="http://msdn.microsoft.com/en-us/library/windows/apps/hh465764.aspx">-ms-high-contrast</a> proposal will be needed (and possibly implemented as <code>contrast-increased: &lt;percent&gt;</code> in combination with the color settings below), but the contrast setting may end up in a restricted category if it's determined to expose the user to privacy or fingerprinting implications.</p>
 
 				<section id="user-color">
-					<h4 class="media-feature"><code>user-color</code></h4>
+					<h4 class="media-feature">Media Feature: <code>user-color</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -252,14 +327,14 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userColors</dd>
+						<dd data-transform="linkRestrictionCategory">userColors</dd>
 						
 					</dl>
 					<p class="ednote">Need to determine how to match color hue or value ranges (potentially via HSL) so that we could expose min/max on colors. Otherwise, this may not be usable.</p>
 				</section>
 
 				<section id="user-background-color">
-					<h4 class="media-feature"><code>user-background-color</code></h4>
+					<h4 class="media-feature">Media Feature: <code>user-background-color</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -272,14 +347,14 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userColors</dd>
+						<dd data-transform="linkRestrictionCategory">userColors</dd>
 						
 					</dl>
 					<p class="ednote">Need to determine how to match color hue or value ranges (potentially via HSL) so that we could expose min/max on colors. Otherwise, this may not be usable.</p>
 				</section>
 
 				<section id="colors-inverted">
-					<h4 class="media-feature"><code>colors-inverted</code></h4>
+					<h4 class="media-feature">Media Feature: <code>colors-inverted</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -292,7 +367,7 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userColors</dd>
+						<dd data-transform="linkRestrictionCategory">userColors</dd>
 						
 					</dl>
 
@@ -358,15 +433,15 @@
 
 				<dl class="properties">
 					<dt>Restriction Category (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionCategory">userFonts</dd>
-					<dt>Default Restriction Type (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionType">none</dd>
+					<dd data-transform="linkRestrictionCategory">userFonts</dd>
+					<dt>Suggested User Agent Restriction</dt>
+					<dd>none</dd>
 				</dl>
 
 				<p class="note">Type settings are not restricted by default from the requesting page, because a site can figure out all of this information by creatively using CSS and JavaScript. These keys are therefore primarily intended as convenience accessors so that web authors can more easily provide adaptive interfaces that work well for all users.</p>
 
 				<section id="user-font-size">
-					<h4 class="media-feature"><code>user-font-size</code></h4>
+					<h4 class="media-feature">Media Feature: <code>user-font-size</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -379,7 +454,7 @@
 						<dd>Yes</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userFonts</dd>
+						<dd data-transform="linkRestrictionCategory">userFonts</dd>
 						
 					</dl>
 
@@ -402,7 +477,7 @@
 				</section>
 
 				<section id="user-line-height">
-					<h4 class="media-feature"><code>user-line-height</code></h4>
+					<h4 class="media-feature">Media Feature: <code>user-line-height</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -415,13 +490,13 @@
 						<dd>Yes</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userFonts</dd>
+						<dd data-transform="linkRestrictionCategory">userFonts</dd>
 						
 					</dl>
 				</section>
 
 				<section id="user-letter-spacing">
-					<h4 class="media-feature"><code>user-letter-spacing</code></h4>
+					<h4 class="media-feature">Media Feature: <code>user-letter-spacing</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -434,13 +509,13 @@
 						<dd>Yes</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userFonts</dd>
+						<dd data-transform="linkRestrictionCategory">userFonts</dd>
 						
 					</dl>
 				</section>
 
 				<section id="user-word-spacing">
-					<h4 class="media-feature"><code>user-word-spacing</code></h4>
+					<h4 class="media-feature">Media Feature: <code>user-word-spacing</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
@@ -453,7 +528,7 @@
 						<dd>Yes</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userFonts</dd>
+						<dd data-transform="linkRestrictionCategory">userFonts</dd>
 						
 					</dl>
 					
@@ -470,39 +545,17 @@
 
 				<dl class="properties">
 					<dt>Restriction Category (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionCategory">userMediaSettings</dd>
-					<dt>Default Restriction Type (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionType">prompt</dd>
+					<dd data-transform="linkRestrictionCategory">userMediaSettings</dd>
+					<dt>Suggested User Agent Restriction</dt>
+					<dd>prompt</dd>
 				</dl>
 
 				<section id="subtitles">
-					<h4 class="media-feature"><code>subtitles</code></h4>
+					<h4 class="media-feature">Media Feature: <code>subtitles</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd><code>on</code> | [<code>off</code>]</dd>
-						
-						<dt>Applies to</dt>
-						<dd>continuous, visual media</dd>
-						
-						<dt>Accepts min/max prefixes</dt>
-						<dd>No</dd>
-						
-						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userMediaSettings</dd>
-						
-					</dl>
-					<p>Matches depending on whether subtitles/captions are displayed (on) or not displayed (off) in native video players. Web authors using a native video player SHOULD allow subtitles to be displayed natively. Web authors using a custom subtitle view SHOULD display the custom-rendered subtitles based on this setting.</p>
-				</section>
-
-				<p class="todo">Todo: Need to determine how to expose list of preferred subtitle languages, which will likely require an object interface rather than a media feature. For example, a native Mexican Spanish speaker living in the United States may have a language preference of "es-mx es en-us en" indicating a preference order for Mexican Spanish, any Spanish, US English, and finally any English dialect. (Note: previously exposed in IndieUI UC draft as DOMString? subtitleLanguages)</p>
-
-				<section id="subtitle-type">
-					<h4 class="media-feature"><code>subtitle-type</code></h4>
-					<dl class="properties">
-						
-						<dt>Value</dt>
-						<dd><code>sdh</code> | <code>cc</code> | [<code>default</code>]</dd>
+						<dd><code>display</code> | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>continuous, visual media</dd>
@@ -511,18 +564,20 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userMediaSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userMediaSettings</dd>
 						
 					</dl>
-					<p class="ednote">Necessary to match preference for subtitles for the deaf and hard of hearing (SDH) over default dialogue-only subtitles, but the preference for closed captions (CC) versus SDH may not be necessary. SDH appears to be generally preferred over CC when available, and a preference for SDH could indicate an implicit preference for CC over dialogue-only subtitles when CC is available but SDH is not.</p>
+					<p>Matches depending on whether subtitles/captions are displayed (display) or not displayed (none) in native video players. Web authors using a native video player SHOULD allow subtitles to be displayed natively. Web authors using a custom subtitle view SHOULD display the custom-rendered subtitles based on this setting.</p>
 				</section>
 
-				<section id="user-subtitle-color">
-					<h4 class="media-feature"><code>user-subtitle-color</code></h4>
+				<p class="todo">Todo: Need to determine how to expose list of preferred subtitle languages, which will likely require an object interface rather than a media feature. For example, a native Mexican Spanish speaker living in the United States may have a language preference of "es-mx es en-us en" indicating a preference order for Mexican Spanish, any Spanish, US English, and finally any English dialect. (Note: previously exposed in IndieUI UC draft as DOMString? subtitleLanguages)</p>
+
+				<section id="subtitle-type">
+					<h4 class="media-feature">Media Feature: <code>subtitle-type</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd>&lt;color&gt; | [<code>undefined</code>]</dd>
+						<dd><code>sdh</code> | <code>cc</code> | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>continuous, visual media</dd>
@@ -531,18 +586,18 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userMediaSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userMediaSettings</dd>
 						
 					</dl>
-					<p class="ednote">Need to determine how to match color hue or value ranges (potentially via HSL) so that we could expose min/max on colors. Otherwise, this may not be usable.</p>
+					<p class="ednote">Necessary to match preference for subtitles for the deaf and hard of hearing (SDH) over default dialogue-only subtitles, but the preference for closed captions (CC) versus SDH may not be necessary. SDH appears to be generally preferred over CC when available, and a preference for SDH could indicate an implicit preference for CC over dialogue-only subtitles when CC is available but SDH is not.</p>
 				</section>
 
-				<section id="user-subtitle-background-color">
-					<h4 class="media-feature"><code>user-subtitle-background-color</code></h4>
+				<section id="user-subtitle-color">
+					<h4 class="media-feature">Media Feature: <code>user-subtitle-color</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd>&lt;color&gt; | [<code>undefined</code>]</dd>
+						<dd>&lt;color&gt; | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>continuous, visual media</dd>
@@ -551,18 +606,38 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userMediaSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userMediaSettings</dd>
+						
+					</dl>
+					<p class="ednote">Need to determine how to match color hue or value ranges (potentially via HSL) so that we could expose min/max on colors. Otherwise, this may not be usable.</p>
+				</section>
+
+				<section id="user-subtitle-background-color">
+					<h4 class="media-feature">Media Feature: <code>user-subtitle-background-color</code></h4>
+					<dl class="properties">
+						
+						<dt>Value</dt>
+						<dd>&lt;color&gt; | [<code>none</code>]</dd>
+						
+						<dt>Applies to</dt>
+						<dd>continuous, visual media</dd>
+						
+						<dt>Accepts min/max prefixes</dt>
+						<dd>No</dd>
+						
+						<dt>Restriction Category (IDL)</dt>
+						<dd data-transform="linkRestrictionCategory">userMediaSettings</dd>
 						
 					</dl>
 					<p class="ednote">Need to determine how to match color hue or value ranges (potentially via HSL) so that we could expose min/max on colors. Otherwise, this may not be usable.</p>
 				</section>
 
 				<section id="audio-description">
-					<h4 class="media-feature"><code>audio-description</code></h4>
+					<h4 class="media-feature">Media Feature: <code>audio-description</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd><code>on</code> | [<code>off</code>]</dd>
+						<dd><code>display</code> | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>continuous, audio media</dd>
@@ -571,7 +646,7 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userMediaSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userMediaSettings</dd>
 						
 					</dl>
 					<p>Matches a user's preference to be presented with an alternate or supplemental audio track describing the information presented visually.</p>
@@ -599,19 +674,19 @@
 
 				<dl class="properties">
 					<dt>Restriction Category (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionCategory">userScreenReaderSettings</dd>
-					<dt>Default Restriction Type (IDL)</dt>
-					<dd data-transform="linkMediaQueryRestrictionType">justification</dd>
+					<dd data-transform="linkRestrictionCategory">userScreenReaderSettings</dd>
+					<dt>Suggested User Agent Restriction</dt>
+					<dd>prompt with author-provided justification</dd>
 				</dl>
 
 				<p>Web authors SHOULD NOT request any keys in this category unless the knowledge is essential to the operation of the web application, and web authors MUST provide a justification for the request as defined in @@ section.</p>
 
 				<section id="screenreader">
-					<h4 class="media-feature"><code>screenreader</code></h4>
+					<h4 class="media-feature">Media Feature: <code>screenreader</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd><code>on</code> | [<code>off</code>]</dd>
+						<dd><code>active</code> | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>interactive media</dd>
@@ -620,19 +695,19 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userScreenReaderSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userScreenReaderSettings</dd>
 						
 					</dl>
-					<p>Matches whether a screen reader is currently active (on) or not (off).</p>
+					<p>Matches whether a screen reader is currently active (active) or not (none).</p>
 				</section>
 
 				<!-- need to consider these a bit more
 				<section id="screenreader-typing-echo">
-					<h4 class="media-feature"><code>screenreader-typing-echo</code></h4>
+					<h4 class="media-feature">Media Feature: <code>screenreader-typing-echo</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd><code>words</code> | <code>characters</code> | <code>both</code> | [<code>undefined</code>]</dd>
+						<dd><code>words</code> | <code>characters</code> | <code>both</code> | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>interactive media</dd>
@@ -641,18 +716,18 @@
 						<dd>No</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userScreenReaderSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userScreenReaderSettings</dd>
 						
 					</dl>
 					<p>Returns a value indicating whether typed speech from a screen reader echos words, characters, or both.</p>
 				</section>
 
 				<section id="screenreader-words-per-minute">
-					<h4 class="media-feature"><code>screenreader-words-per-minute</code></h4>
+					<h4 class="media-feature">Media Feature: <code>screenreader-words-per-minute</code></h4>
 					<dl class="properties">
 						
 						<dt>Value</dt>
-						<dd>&lt;number&gt; | [<code>undefined</code>]</dd>
+						<dd>&lt;number&gt; | [<code>none</code>]</dd>
 						
 						<dt>Applies to</dt>
 						<dd>interactive media</dd>
@@ -661,7 +736,7 @@
 						<dd>Yes</dd>
 						
 						<dt>Restriction Category (IDL)</dt>
-						<dd data-transform="linkMediaQueryRestrictionCategory">userScreenReaderSettings</dd>
+						<dd data-transform="linkRestrictionCategory">userScreenReaderSettings</dd>
 						
 					</dl>
 					<p>Returns a number indicating the approximate words-per-minute rate of a screen reader user's text-to-speech settings.</p>
@@ -671,7 +746,7 @@
 			</section>
 			<!-- :::::::::::::::::::: END userScreenReaderSettings :::::::::::::::::::: -->
 
-			<p class="todo">Todo: Probably need additional categories for screen magnifier (on/off, scale factor), switch control (on/off), and the more general "api-interoperable" key which could be used automation scripts in addition to real assistive technology.</p>
+			<p class="todo">Todo: Probably need additional categories for screen magnifier (active/none, scale factor), switch control (active/none), and the more general "api-compatible" key which could be used automation scripts in addition to real assistive technology.</p>
 			<p class="todo">Todo: Need a mockup of an example user prompt with displayed justification string.</p>
 
 
@@ -690,7 +765,9 @@
 		
 		<!-- Todo: Glossary currently includes all terms in Events Module and User Context Module. -->
 		<!-- Need to remove the ones that are not used in the current document. -->
-		<section id="terms" class="appendix" data-DISABLE-include="./include/terms.html"></section>
+		<!-- Commented for now 
+		<section id="terms" class="appendix" data-include="./include/terms.html"></section>
+		-->
 
 		<section id="acknowledgements" class="appendix" data-include="./include/ack.html"></section>
 		
--- a/src/js/respec-transformers.js	Tue Dec 17 11:34:31 2013 -0500
+++ b/src/js/respec-transformers.js	Tue Dec 17 17:42:52 2013 -0800
@@ -37,10 +37,10 @@
 
 // utility used by listMediaFeatures
 function allMediaFeatures() {
-	var node, selector = '', mediaFeatureList = [], nodeList = $$('.media-feature');
+	var mf, mediaFeatureList = [], nodeList = $$('.media-feature code');
 	for (var i=0; i < nodeList.length; i++) {
-		node = nodeList[i].parentElement.id;
-		mediaFeatureList.push(node);
+		mf = nodeList[i].innerText || nodeList[i].textContent;
+		mediaFeatureList.push(mf);
 	}
 	return mediaFeatureList.sort();
 }
@@ -62,11 +62,8 @@
 	var link = optLink || content;
 	return ['<a href="#', r.xmlEscape(link), '">', content, '</a>'].join('');	
 }
-function linkMediaQueryRestrictionCategory(r, content) {
-	return linkId(r, content, ("idl-def-MediaQueryRestrictionCategory." + content));
-}
-function linkMediaQueryRestrictionType(r, content) {
-	return linkId(r, content, ("idl-def-MediaQueryRestrictionType." + content));
+function linkRestrictionCategory(r, content) {
+	return linkId(r, content, ("idl-def-RestrictionCategory." + content));
 }
 
 
--- a/src/obsolete/key-value-context.html	Tue Dec 17 11:34:31 2013 -0500
+++ b/src/obsolete/key-value-context.html	Tue Dec 17 17:42:52 2013 -0800
@@ -1,7 +1,94 @@
+<!DOCTYPE html>
+<html lang="en-us">
+	<head>
+		<meta http-equiv="Content-type" content="text/html; charset=utf-8">
+		<title>IndieUI 1.0: User Context</title>
+		<link href="./css/screen.css" rel="stylesheet" type="text/css">
+		<script type="text/javascript" class="remove" src="./loc/en/strings.js"></script>
+		<script type="text/javascript" class="remove" src="./js/utils.js"></script>
+		<script type="text/javascript" class="remove" src="./js/respec-transformers.js"></script>
+		
+		<!-- 
+      === NOTA BENE ===
+      For the three scripts below, if your spec resides on dev.w3 you can check them
+      out in the same tree and use relative links so that they'll work offline,
+     -->
+		<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
+		<script class="remove">
+      var respecConfig = {
+          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
+          specStatus:           "ED",
+          
+          // the specification's short name, as in http://www.w3.org/TR/short-name/
+          shortName:            "indie-ui-context",
 
+          // if your specification has a subtitle that goes below the main
+          // formal title, define it here
+          subtitle   :  "Contextual Information for User Interface Independence",
+
+          // if you wish the publication date to be other than today, set this
+          // publishDate:  "2009-08-06",
+
+          // if the specification's copyright date is a range of years, specify
+          // the start date here:
+          // copyrightStart: "2012",
+
+          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
+          // and its maturity status
+          // previousPublishDate:  "1977-03-15",
+          // previousMaturity:  "WD",
+
+          // if there a publicly available Editor's Draft, this is the link
+          edDraftURI:           "http://dvcs.w3.org/hg/IndieUI/raw-file/default/src/indie-ui-context.html",
+
+          // if this is a LCWD, uncomment and set the end of its review period
+          // lcEnd: "2009-08-05",
+
+          // if you want to have extra CSS, append them to this list
+          // it is recommended that the respec.css stylesheet be kept
+          // extraCSS:             [
+          //   "http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css",
+          //   "./css/screen.css"
+          // ],
+
+          // editors, add as many as you like
+          // only "name" is required, also can have url, company, companyURL in comma separated list
+          editors:  [
+              { name: "James Craig", company: "Apple Inc.", companyURL: "http://www.apple.com/" },
+              // Commenting Michael's name for now, since this document is in need of serious work, and that's no fault of his.
+              // { name: "Michael Cooper", company: "W3C", companyURL: "http://www.w3.org/" },
+          ],
+
+          // authors, add as many as you like. 
+          // This is optional, uncomment if you have authors as well as editors.
+          // only "name" is required. Same format as editors.
+
+          //authors:  [
+          //  { name: "James Craig", company: "Apple Inc.", companyURL: "http://www.apple.com/" },
+          //],
+          
+          // name of the WG
+          wg:           "Independent User Interface (Indie UI) and Web Events Working Groups",
+          
+          // URI of the public WG page
+          wgURI:        "http://www.w3.org/WAI/IndieUI/",
+          
+          // name (without the @w3c.org) of the public mailing to which comments are due
+          wgPublicList: "public-indie-ui-comments",
+          
+          // URI of the patent status for this WG, for Rec-track documents
+          // !!!! IMPORTANT !!!!
+          // This is important for Rec-track documents, do not copy a patent URI from a random
+          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
+          // Team Contact.
+          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/54953/status",
+      };
+    </script>
+		
+	</head>
+	<body>
 		<!-- :::::::::::::::::::: window.settings :::::::::::::::::::: -->
-		<!-- obsolete, marking as hidden -->
-		<section id="UserSettings" hidden>
+		<section id="UserSettings">
 			<h3>Interface UserSettings</h3>
 			<p>The <code>settings</code> attribute of the Window interface MUST return an instance of the UserSettings interface. The same object must be returned each time.</p>
 
@@ -15,10 +102,10 @@
 					<pre class="example" data-transform="syntaxJavaScript">
 						// example of a preference defined within the IndieUI User Context specification.
 						window.settings.valueForKey('fontSize'); // e.g. '16px'
-						window.settings.valueForKey('subtitle'); // e.g. returns true if the user wants to see subtitles or captions by default
+						window.settings.valueForKey('subtitles'); // e.g. returns true if the user wants to see subtitles or captions by default
 						
 						// example of an vendor-proposed preference, intended for standardization.
-						window.settings.valueForKey('foo', 'webkit');
+						window.settings.valueForKey('someVendorSpecificPreference', 'vendor');
 						
 					</pre>
 					<dl class="parameters">
@@ -165,7 +252,6 @@
 
 		
 		<!-- :::::::::::::::::::: window.accessibility :::::::::::::::::::: -->
-		<!-- Commented b/c this section is mostly overcome by other features or specs. Leaving comments as some of these may be pulled back in but reformatted.
 		<section id="identification">
 			<h2>Assistive Technology Identification and Notification</h2>
 			<p class="ednote">Most of this section is out-of-date. Please don't put too much effort into change requests yet.</p>
@@ -317,13 +403,11 @@
   <span class="comment">// potential method: speech.recognition.updateDictionary() to capture correct pronunciation of uncommon or app-specific words</span>
 };</code></pre>
 			</div>
-			-->
 		</section>
 		<!-- :::::::::::::::::::: END window.accessibility :::::::::::::::::::: -->
 		
 		
 		<!-- :::::::::::::::::::: Accessibility Event Interfaces :::::::::::::::::::: -->
-		<!--
 		<section id="AccessibilityEvents">
 			<h2>Accessibility Events</h2>
 			
@@ -363,7 +447,7 @@
 				</section>
 			</section>
 		</section>
-		-->
 		<!-- :::::::::::::::::::: END Accessibility Event Interfaces :::::::::::::::::::: -->
 		
-		
\ No newline at end of file
+	</body>
+</html>