introduce some more terminology

Author: annevk

cssom/Overview.html

@@ -25,13 +25,13 @@
   <div class=head>
    <h1 id=cssom>CSSOM</h1>
 
-   <h2 class="no-num no-toc" id="">Editor's Draft 1 December 2009</h2>
+   <h2 class="no-num no-toc" id="">Editor's Draft 2 December 2009</h2>
 
    <dl>
     <dt>This Version:
 
     <dd><a
-     href="http://www.w3.org/TR/2009/ED-cssom-20091201/">http://www.w3.org/TR/2009/ED-cssom-20091201/</a>
+     href="http://www.w3.org/TR/2009/ED-cssom-20091202/">http://www.w3.org/TR/2009/ED-cssom-20091202/</a>
 
     <dt>Latest Version:
 
@@ -317,6 +317,7 @@ <h2 id=media-queries><span class=secno>4. </span>Media Queries</h2>
   <p><dfn id="media queries">Media queries</dfn> are defined by the Media
    Queries specification. This section defines various concepts around media
    queries, including their API and serialization form.</p>
+  <!-- XXX maybe not a <dfn> -->
   <!-- XXX ref -->
 
   <h3 id=parsing-media-queries><span class=secno>4.1. </span>Parsing Media
@@ -1575,7 +1576,6 @@ <h4 id=requirements-on-user-agents-implementing0><span class=secno>6.3.4.
    title="">Link</code> Header</h4>
   <!-- XXX ref, one day -->
   <!-- XXX deal with media param -->
-  <!-- XXX title* param does not work (how unexpected -->
 
   <p>For each HTTP <code title=http-link>Link</code> header of which one of
    the link relation types is an <a href="#ascii-case-insensitive">ASCII
@@ -2146,12 +2146,6 @@ <h4 id=the-cssnamespacerule-interface><span class=secno>7.2.8. </span>The
 
   <h3 id=css-declaration-blocks><span class=secno>7.3. </span>CSS Declaration
    Blocks</h3>
-  <!--
-   concept: CSS declaration block
-   members: CSS declaration block readonly flag
-            CSS declaration block value type flag
-            collection of CSS declarations
-  -->
 
   <p class=XXX>To <dfn id=parse-a-css-declaration-block>parse a CSS
    declaration block</dfn> ...
@@ -2412,9 +2406,35 @@ <h4 id=examples0><span class=secno>7.3.1. </span>Examples</h4>
   <h4 id=the-cssstyledeclaration-interface><span class=secno>7.3.2.
    </span>The <code title="">CSSStyleDeclaration</code> Interface</h4>
 
-  <p>The <code><a href="#cssstyledeclaration">CSSStyleDeclaration</a></code>
-   interface gives access to read and manipulate CSS properties and their
-   values within a declaration block.
+  <p>Objects implementing the <code><a
+   href="#cssstyledeclaration">CSSStyleDeclaration</a></code> interface give
+   access to read and manipulate CSS properties and their values within a
+   declaration block.
+
+  <p>Objects implementing the <code><a
+   href="#cssstyledeclaration">CSSStyleDeclaration</a></code> interface have
+   the following associated concepts:
+
+  <dl>
+   <dt><dfn id=css-declaration-block-readonly-flag>CSS declaration block
+    readonly flag</dfn>
+
+   <dd>
+    <p>Indicates whether or not the object can be modified (as detailed
+     below). True when it cannot. False otherwise and by default.
+   </dd>
+   <!--
+   <dt><dfn>CSS declaration block value type</dfn></dt>
+   <dd><p>Indicates the type of value 
+   
+   -->
+
+   <dt><dfn id=collection-of-css-declarations>collection of CSS
+    declarations</dfn>
+
+   <dd>
+    <p>The CSS declarations associated with the object.
+  </dl>
 
   <p>If an attribute or method returns an object implementing the <code><a
    href="#cssstyledeclaration">CSSStyleDeclaration</a></code> interface (and
@@ -2430,10 +2450,6 @@ <h4 id=the-cssstyledeclaration-interface><span class=secno>7.3.2.
    of that.</p>
   <!-- XXX we should define this in more detail -->
 
-  <p class=issue><code><a
-   href="#cssstyledeclaration">CSSStyleDeclaration</a></code> can represent
-   computed values and used values.
-
   <pre
    class=idl>interface <dfn id=cssstyledeclaration>CSSStyleDeclaration</dfn> {
            attribute DOMString <a href="#cssstyledeclaration-csstext" title=cssstyledeclaration-csstext>cssText</a>;
@@ -2575,19 +2591,28 @@ <h4 id=the-cssstyledeclaration-interface><span class=secno>7.3.2.
    title=cssstyledeclaration-csstext><code>cssText</code></dfn> attribute <em
    class=ct>must</em>, on getting, return the result of <a
    href="#serialize-a-css-declaration-block" title="serialize a CSS
-   declaration block">serializing</a> the <span>CSS declaration block</span>.
+   declaration block">serializing</a> the <a
+   href="#collection-of-css-declarations">collection of CSS declarations</a>.
 
   <p>On setting the <code title="">cssText</code> attribute these steps <em
    class=ct>must</em> be run:
 
   <ol>
    <li>
-    <p>Remove the <span>list of associated declarations</span>.
+    <p>If the <a href="#css-declaration-block-readonly-flag">CSS declaration
+     block readonly flag</a> is true raise a
+     <code>NO_MODIFICATION_ALLOWED_ERR</code> and terminate this algorithm.
+
+   <li>
+    <p>Empty the <a href="#collection-of-css-declarations">collection of CSS
+     declarations</a>.
 
    <li>
     <p><a href="#parse-a-css-declaration-block" title="Parse a CSS
      declaration block">Parse</a> the given value and, if the return value is
-     not null, append it to the <span>list of associated declarations</span>.
+     not null, append it to the <a
+     href="#collection-of-css-declarations">collection of CSS
+     declarations</a>.
   </ol>
 
   <p>The <dfn id=cssstyledeclaration-getpropertyvalue
@@ -2609,37 +2634,55 @@ <h4 id=the-cssstyledeclaration-interface><span class=secno>7.3.2.
   <p class=example>E.g. for <code>background-color:lime !IMPORTANT</code> the
    return value would be "<code title="">important</code>".
 
-  <p>The <dfn id=cssstyledeclaration-removeproperty
+  <p>When the <dfn id=cssstyledeclaration-removeproperty
    title=cssstyledeclaration-removeproperty><code>removeProperty(<var
-   title="">property</var>)</code></dfn> method, when invoked, if <var
-   title="">property</var> case-insensitively matches a specified property
-   user agents <em class=ct>must</em> remove that property declaration.
+   title="">property</var>)</code></dfn> method is invoked these steps <em
+   class=ct>must</em> be run:
+
+  <ol>
+   <li>
+    <p>If the <a href="#css-declaration-block-readonly-flag">CSS declaration
+     block readonly flag</a> is true raise a
+     <code>NO_MODIFICATION_ALLOWED_ERR</code> and terminate this algorithm.
+
+   <li>
+    <p>If <var title="">property</var> is an <a
+     href="#ascii-case-insensitive">ASCII case-insensitive</a> match for a
+     property of a declaration in the <a
+     href="#collection-of-css-declarations">collection of CSS
+     declarations</a> remove the declaration.</p>
+  </ol>
 
-  <p>The <dfn id=cssstyledeclaration-setproperty
+  <p>When the <dfn id=cssstyledeclaration-setproperty
    title=cssstyledeclaration-setproperty><code>setProperty(<var
    title="">property</var>, <var title="">value</var>, <var
-   title="">priority</var>)</code></dfn> method gives a way to set a
-   declaration. When invoked, user agents <em class=ct>must</em> run the
-   following steps:
+   title="">priority</var>)</code></dfn> method is invoked these steps <em
+   class=ct>must</em> be run:
 
   <ol>
+   <li>
+    <p>If the <a href="#css-declaration-block-readonly-flag">CSS declaration
+     block readonly flag</a> is true raise a
+     <code>NO_MODIFICATION_ALLOWED_ERR</code> and terminate this algorithm.
+
    <li>
     <p>If <var title="">property</var> does not case-insensitively match a
-     supported property abort this algorithm.
+     supported property terminate this algorithm.
 
    <li>
-    <p>If <var title="">value</var> is <code>null</code> or the empty string
-     invoke <code title=cssstyledeclaration-removeproperty><a
-     href="#cssstyledeclaration-removeproperty">removeProperty</a></code>
-     with <var title="">property</var> as argument and abort this algorithm.
+    <p>If <var title="">value</var> is null or the empty string invoke <code
+     title=cssstyledeclaration-removeproperty><a
+     href="#cssstyledeclaration-removeproperty">removeProperty()</a></code>
+     with <var title="">property</var> as argument and terminate this
+     algorithm.
 
    <li>
     <p>If the <var title="">priority</var> argument has been omitted let <var
-     title="">priority</var> be <code>null</code>.
+     title="">priority</var> be the empty string.
 
    <li>
-    <p>If <var title="">priority</var> is neither a valid priority nor
-     <code>null</code> or the empty string abort this algorithm.
+    <p>If <var title="">priority</var> is neither a valid priority nor the
+     empty string terminate this algorithm.
 
    <li>
     <p>If <a href="#parse-a-css-value" title="parse a CSS value">parsing the
@@ -2651,14 +2694,15 @@ <h4 id=the-cssstyledeclaration-interface><span class=secno>7.3.2.
    <li>
     <p>Finally, set <var title="">property</var> to <var title="">value</var>
      with priority <var title="">priority</var> when <var
-     title="">priority</var> is not <code>null</code> or the empty string.
-     Otherwise set <var title="">property</var> to <var title="">value</var>.
+     title="">priority</var> is not the empty string. Otherwise set <var
+     title="">property</var> to <var title="">value</var>.
   </ol>
   <!-- XXX WebIDL work -->
 
   <p>The <dfn id=cssstyledeclaration-length
    title=cssstyledeclaration-length><code>length</code></dfn> attribute <em
-   class=ct>must</em> be the number of setted properties.
+   class=ct>must</em> return the number of declarations in the <a
+   href="#collection-of-css-declarations">collection of CSS declarations</a>.
 
   <p>The <dfn id=cssstyledeclaration-item
    title=cssstyledeclaration-item><code>item(<var
@@ -2674,15 +2718,16 @@ <h4 id=the-cssstyledeclaration-interface><span class=secno>7.3.2.
    associated with or <code>null</code> if it is not associated with a
    <code><a href="#cssrule">CSSrule</a></code> object.</p>
   <!-- XXX introduce a concept for this instead -->
+  <!-- XXX define this in terms of getPropertyValue/setProperty -->
 
-  <p>The IDL attribute in the first column <em class=ct>must</em>, on getting
-   return the value for the CSS property given in the second column on the
-   same row.</p>
+  <p>For the table below, the IDL attribute in the first column <em
+   class=ct>must</em>, on getting return the value for the CSS property given
+   in the second column on the same row.</p>
   <!-- XXX ref -->
 
-  <p>On setting the IDL attribute in the first column the value for the CSS
-   property giving in the second column on the same row <em
-   class=ct>must</em> be set to the given value.</p>
+  <p>Similarly for the table below, on setting the IDL attribute in the first
+   column the value for the CSS property giving in the second column on the
+   same row <em class=ct>must</em> be set to the given value.</p>
   <!-- XXX ref, exceptions for readonly objects -->
 
   <table>