address Tab's editorial comments re intros, notes <http://lists.w3.org/Archives/Public/public-device-apis/2012Dec/0050.html>
authorAnssi Kostiainen <anssi.kostiainen@nokia.com>
Thu, 10 Jan 2013 14:41:23 +0200
changeset 329 1c5fc74bd529
parent 328 51296676e203
child 330 78129450e57a
address Tab's editorial comments re intros, notes <http://lists.w3.org/Archives/Public/public-device-apis/2012Dec/0050.html>
light/Overview.html
--- a/light/Overview.html	Thu Jan 10 13:29:01 2013 +0200
+++ b/light/Overview.html	Thu Jan 10 14:41:23 2013 +0200
@@ -52,31 +52,12 @@
     <section class="informative">
       <h2>Introduction</h2>
       <p>
-        The <a>DeviceLightEvent</a> interface provides web developers
-        information about the ambient light levels near the
-        hosting in terms of lux units.
-      </p>
-      <p>
-        The <a>LightLevelEvent</a> interface provides web
-        developers information about the ambient light
-        levels near the hosting in terms of general ranges.
-      </p>
-      <p>
-        The values of the <a>LightLevelEvent</a> event may
-        be "normal", "dim", or "bright".  "bright" is
-        supposed to mean "direct sunlight, or similarly
-        bright conditions that make it hard to see things
-        that aren't high-contrast".  "dim" is supposed to
-        mean "dark enough that the light produced by a white
-        background is eye-straining or distracting".  The
-        lux values for "dim" typical begin below 50, and the
-        values for "bright" begin above 10000.
-      </p>
-        
-
-      <p>
-        This is achieved by interrogating a photosensors or similar detectors
-        of a device.
+        This specification defines events that provide information about the
+        ambient light level, as measured by a device's light sensor.  A
+        <a>LightLevelEvent</a> describes the light level as one of three simple
+        categories - "dim", "normal", and "bright" - while a
+        <a>DeviceLightEvent</a> provides a more granular answer by describing
+        the light level in terms of lux units.
       </p>
     </section>
     
@@ -130,6 +111,11 @@
     <section>
       <h2>Device Light</h2>
       <p>
+        The <a>DeviceLightEvent</a> interface provides information about the
+        ambient light levels, as detected by the device's light detector, in
+        terms of lux units.
+      </p>
+      <p>
         The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
         which this specification extends:
       </p>
@@ -166,6 +152,11 @@
           object is created, this attribute MUST be initialized to positive
           Infinity. It represents the <a>current light level</a>.
         </p>
+        <div class="note">
+          The precise lux value reported by different devices in the same light
+          can be different, due to differences in detection method, sensor
+          construction etc.
+        </div>
         <p>
           When a <dfn>user agent</dfn> is required to <dfn>fire a device
           light event</dfn>, the <dfn>user agent</dfn> MUST run the
@@ -226,6 +217,11 @@
     <section>
       <h2>Light Level</h2>
       <p>
+        The <a>LightLevelEvent</a> interface provides information about the
+        ambient light levels, as detected by the device's light detector, in
+        terms of three general range: "dim", "normal", or "bright".
+      </p>
+      <p>
         The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
         which this specification extends:
       </p>
@@ -301,8 +297,13 @@
                   <li><code>bright</code></li>
                 </ul>
                 <div class="note">
-                  The lux ranges that map to the <a>current light level state</a>s
-                  are left to the implementation.
+                  The lux ranges that map to the <a>current light level
+                  state</a>s are left to the implementation, as devices with
+                  different sensitivities could map them slightly differently.
+                  However, it is recommended that "dim" correspond to ambient
+                  light below 50 lux, "normal" correspond to light between
+                  50 lux and 10000 lux, and "bright" correspond to light
+                  above 10000 lux.
                 </div>
               </li>
             </ol>