[css3-cascade] Add section defining how shorthands work

Author: tabatkins

css3-cascade/Overview.html

@@ -131,63 +131,66 @@ <h2 class="no-num no-toc" id=table-of-contents> Table of contents</h2>
    <li><a href="#at-import"><span class=secno>2. </span> Importing style
     sheets: the ‘<code class=css>@import</code>’ rule</a>
 
-   <li><a href="#cascade-and-inheritance"><span class=secno>3. </span>
+   <li><a href="#shorthand"><span class=secno>3. </span> Shorthand
+    Properties</a>
+
+   <li><a href="#cascade-and-inheritance"><span class=secno>4. </span>
     Cascading and Inheritance</a>
     <ul class=toc>
-     <li><a href="#filter-declarations"><span class=secno>3.1. </span>
+     <li><a href="#filter-declarations"><span class=secno>4.1. </span>
       Filtering Declarations</a>
 
-     <li><a href="#cascade"><span class=secno>3.2. </span> Cascading
+     <li><a href="#cascade"><span class=secno>4.2. </span> Cascading
       Declarations</a>
       <ul class=toc>
-       <li><a href="#cascading-origins"><span class=secno>3.2.1. </span>
+       <li><a href="#cascading-origins"><span class=secno>4.2.1. </span>
         Cascading Origins</a>
 
-       <li><a href="#important-rules"><span class=secno>3.2.2. </span>
+       <li><a href="#important-rules"><span class=secno>4.2.2. </span>
         ‘<code class=css>!important</code>’ rules</a>
 
-       <li><a href="#preshint"><span class=secno>3.2.3. </span> Precedence of
+       <li><a href="#preshint"><span class=secno>4.2.3. </span> Precedence of
         Non-CSS Presentational Hints</a>
 
-       <li><a href="#cascaded-value"><span class=secno>3.2.4. </span> The
+       <li><a href="#cascaded-value"><span class=secno>4.2.4. </span> The
         Cascaded Value</a>
       </ul>
 
-     <li><a href="#defaulting"><span class=secno>3.3. </span> Inheritance and
+     <li><a href="#defaulting"><span class=secno>4.3. </span> Inheritance and
       Defaulting</a>
       <ul class=toc>
-       <li><a href="#initial"><span class=secno>3.3.1. </span> Initial value:
+       <li><a href="#initial"><span class=secno>4.3.1. </span> Initial value:
         the ‘<code class=css>initial</code>’ keyword </a>
 
-       <li><a href="#inheritance"><span class=secno>3.3.2. </span>
+       <li><a href="#inheritance"><span class=secno>4.3.2. </span>
         Inheritance: the ‘<code class=css>inherit</code>’ keyword </a>
 
-       <li><a href="#default-keyword"><span class=secno>3.3.3. </span>
+       <li><a href="#default-keyword"><span class=secno>4.3.3. </span>
         Rolling back the cascade: the ‘<code class=css>default</code>’
         keyword</a>
       </ul>
     </ul>
 
-   <li><a href="#value-stages"><span class=secno>4. </span> Stages of Value
+   <li><a href="#value-stages"><span class=secno>5. </span> Stages of Value
     Computation</a>
     <ul class=toc>
-     <li><a href="#specified"><span class=secno>4.1. </span> Finding the
+     <li><a href="#specified"><span class=secno>5.1. </span> Finding the
       specified value</a>
 
-     <li><a href="#computed"><span class=secno>4.2. </span> Finding the
+     <li><a href="#computed"><span class=secno>5.2. </span> Finding the
       computed value</a>
 
-     <li><a href="#used"><span class=secno>4.3. </span> Finding the used
+     <li><a href="#used"><span class=secno>5.3. </span> Finding the used
       value</a>
 
-     <li><a href="#actual"><span class=secno>4.4. </span> Finding the actual
+     <li><a href="#actual"><span class=secno>5.4. </span> Finding the actual
       value</a>
 
-     <li><a href="#stages-examples"><span class=secno>4.5. </span>
+     <li><a href="#stages-examples"><span class=secno>5.5. </span>
       Examples</a>
     </ul>
 
-   <li><a href="#conformance"><span class=secno>5. </span>Conformance</a>
+   <li><a href="#conformance"><span class=secno>6. </span>Conformance</a>
 
    <li class=no-num><a href="#acknowledgments">Acknowledgments</a>
 
@@ -274,13 +277,75 @@ <h2 id=at-import><span class=secno>2. </span> Importing style sheets: the
    Specifying ‘<code class=css>all</code>’ for the medium has the same
    effect.
 
-  <h2 id=cascade-and-inheritance><span class=secno>3. </span> Cascading and
+  <h2 id=shorthand><span class=secno>3. </span> Shorthand Properties</h2>
+
+  <p> Some properties are <dfn id=shorthand-properties>shorthand
+   properties</dfn>, meaning that they allow authors to specify the values of
+   several properties with a single property. A shorthand property sets all
+   of its longhand sub-properties, exactly as if expanded in place.
+
+  <div class=example>
+   <p> For example, the CSS 2.1 ‘<code class=property>font</code>’
+    property is a shorthand property for setting ‘<code
+    class=property>font-style</code>’, ‘<code
+    class=property>font-variant</code>’, ‘<code
+    class=property>font-weight</code>’, ‘<code
+    class=property>font-size</code>’, ‘<code
+    class=property>line-height</code>’, and ‘<code
+    class=property>font-family</code>’ all at once. The multiple style
+    rules of this example:
+
+   <pre>
+h1 { 
+  font-weight: bold; 
+  font-size: 12pt;
+  line-height: 14pt; 
+  font-family: Helvetica; 
+  font-variant: normal;
+  font-style: normal;
+}</pre>
+
+   <p>can therefore be rewritten as
+
+   <pre>h1 { font: bold 12pt/14pt Helvetica }</pre>
+  </div>
+
+  <p> When values are omitted from a shorthand form, unless otherwise
+   defined, each "missing" sub-property is assigned its <a
+   href="#initial-value"><i>initial value</i></a>.
+
+  <p class=note> This means that a shorthand property declaration always sets
+   <em title="">all</em> of its subproperties, even those that are not
+   explicitly set. Carelessly used, this might result in inadvertently
+   resetting some sub-properties. Carefully used, a shorthand can guarantee a
+   "blank slate" by resetting sub-properties inadvertently cascaded from
+   other sources. For example, writing ‘<code class=css>background:
+   green</code>’ rather than ‘<code class=css>background-color:
+   green</code>’ ensures that the background color overrides any earlier
+   declarations that might have set the background to an image.
+
+  <p> In some cases, a shorthand might have different syntax or special
+   keywords that don't directly correspond to values of its sub-properties.
+   (In such cases, the shorthand will explicitly define the expansion of its
+   values.)
+
+  <p> If a shorthand is specified as one of the <a
+   href="http://www.w3.org/TR/css3-values/">CSS-wide keywords</a>, it sets
+   all of its sub-properties to that keyword. (Note that these keywords
+   cannot be combined with other values in a single declaration, not even in
+   a shorthand.)
+
+  <p> Declaring a shorthand property to be ‘<code
+   class=css>!important</code>’ is equivalent to declaring all of its
+   sub-properties to be "!important".
+
+  <h2 id=cascade-and-inheritance><span class=secno>4. </span> Cascading and
    Inheritance</h2>
 
   <p> The cascading and inheritance process takes a set of declarations as
    input, and outputs a specified value for each property on each element.
 
-  <h3 id=filter-declarations><span class=secno>3.1. </span> Filtering
+  <h3 id=filter-declarations><span class=secno>4.1. </span> Filtering
    Declarations</h3>
 
   <p> In order to find the specified values, implementations must first
@@ -302,7 +367,7 @@ <h3 id=filter-declarations><span class=secno>3.1. </span> Filtering
    unordered list of values. The next section, the cascade process, orders
    these lists.
 
-  <h3 id=cascade><span class=secno>3.2. </span> Cascading Declarations</h3>
+  <h3 id=cascade><span class=secno>4.2. </span> Cascading Declarations</h3>
 
   <p> The cascade algorithm takes an unordered list of declarations for a
    given property on an element and sorts it by precedence as determined
@@ -367,7 +432,7 @@ <h3 id=cascade><span class=secno>3.2. </span> Cascading Declarations</h3>
    (potentially empty) sorted list of declarations for each property on each
    element.
 
-  <h4 id=cascading-origins><span class=secno>3.2.1. </span> Cascading Origins</h4>
+  <h4 id=cascading-origins><span class=secno>4.2.1. </span> Cascading Origins</h4>
 
   <p> Each style rule has an origin, which determines where it enters the
    cascade. CSS defines three core origins:
@@ -421,7 +486,7 @@ <h4 id=cascading-origins><span class=secno>3.2.1. </span> Cascading Origins</h4>
     generate "virtual" rules representing their effects when running.
   </dl>
 
-  <h4 id=important-rules><span class=secno>3.2.2. </span> ‘<code
+  <h4 id=important-rules><span class=secno>4.2.2. </span> ‘<code
    class=css>!important</code>’ rules</h4>
 
   <p> CSS attempts to create a balance of power between author and user style
@@ -469,7 +534,7 @@ <h4 id=important-rules><span class=secno>3.2.2. </span> ‘<code
 p { font-size: 24pt }</pre>
   </div>
 
-  <h4 id=preshint><span class=secno>3.2.3. </span> Precedence of Non-CSS
+  <h4 id=preshint><span class=secno>4.2.3. </span> Precedence of Non-CSS
    Presentational Hints</h4>
 
   <p> The UA may choose to honor presentational hints in a source document's
@@ -490,7 +555,7 @@ <h4 id=preshint><span class=secno>3.2.3. </span> Precedence of Non-CSS
    the appropriate level for presentational hints with these considerations
    in mind.
 
-  <h4 id=cascaded-value><span class=secno>3.2.4. </span> The Cascaded Value</h4>
+  <h4 id=cascaded-value><span class=secno>4.2.4. </span> The Cascaded Value</h4>
 
   <p> The <dfn id=cascaded-value0>cascaded value</dfn> represents the result
    of the cascade. It is the value of the highest declaration in the <a
@@ -503,7 +568,7 @@ <h4 id=cascaded-value><span class=secno>3.2.4. </span> The Cascaded Value</h4>
    its property definition table) or the ‘<code class=css>initial</code>’
    keyword otherwise.
 
-  <h3 id=defaulting><span class=secno>3.3. </span> Inheritance and Defaulting</h3>
+  <h3 id=defaulting><span class=secno>4.3. </span> Inheritance and Defaulting</h3>
 
   <p> In most cases, the <a href="#specified-value"><i>specified
    value</i></a> is the <a href="#cascaded-value0"><i>cascaded value</i></a>.
@@ -512,7 +577,7 @@ <h3 id=defaulting><span class=secno>3.3. </span> Inheritance and Defaulting</h3>
    values are handled specially when they are the <a
    href="#cascaded-value0"><i>cascaded value</i></a> of a property.
 
-  <h4 id=initial><span class=secno>3.3.1. </span> Initial value: the ‘<code
+  <h4 id=initial><span class=secno>4.3.1. </span> Initial value: the ‘<code
    class=css>initial</code>’ keyword</h4>
 
   <p> Each property has an <dfn id=initial-value>initial value</dfn>, defined
@@ -522,7 +587,7 @@ <h4 id=initial><span class=secno>3.3.1. </span> Initial value: the ‘<code
    href="#initial-value"><i>initial value</i></a> becomes its <a
    href="#specified-value"><i>specified value</i></a>.
 
-  <h4 id=inheritance><span class=secno>3.3.2. </span> Inheritance: the
+  <h4 id=inheritance><span class=secno>4.3.2. </span> Inheritance: the
    ‘<code class=css>inherit</code>’ keyword</h4>
 
   <p> Some properties are <dfn id=inherited-properties
@@ -553,7 +618,7 @@ <h4 id=inheritance><span class=secno>3.3.2. </span> Inheritance: the
    href="#inherited-value"><i>inherited value</i></a> becomes the property's
    <i>specified</i> and <a href="#computed-value"><i>computed values</i></a>.
 
-  <h4 id=default-keyword><span class=secno>3.3.3. </span> Rolling back the
+  <h4 id=default-keyword><span class=secno>4.3.3. </span> Rolling back the
    cascade: the ‘<code class=css>default</code>’ keyword</h4>
 
   <p> CSS Cascading and Inheritance Level 3 introduces the ‘<code
@@ -569,7 +634,7 @@ <h4 id=default-keyword><span class=secno>3.3.3. </span> Rolling back the
    class=css>default</code>’ or until the <a
    href="#output-of-the-cascade"><i>output of the cascade</i></a> is empty.
 
-  <h2 id=value-stages><span class=secno>4. </span> Stages of Value
+  <h2 id=value-stages><span class=secno>5. </span> Stages of Value
    Computation</h2>
 
   <p> Once a user agent has parsed a document and constructed a document
@@ -595,7 +660,7 @@ <h2 id=value-stages><span class=secno>4. </span> Stages of Value
     local environment.
   </ul>
 
-  <h3 id=specified><span class=secno>4.1. </span> Finding the specified value</h3>
+  <h3 id=specified><span class=secno>5.1. </span> Finding the specified value</h3>
 
   <p> The <dfn id=specified-value>specified value</dfn> is the output of the
    <a href="#cascade-and-inheritance">cascading and inheritance process</a>.
@@ -604,7 +669,7 @@ <h3 id=specified><span class=secno>4.1. </span> Finding the specified value</h3>
    href="#specified-value"><i>specified value</i></a> exists for every
    property on every element.
 
-  <h3 id=computed><span class=secno>4.2. </span> Finding the computed value</h3>
+  <h3 id=computed><span class=secno>5.2. </span> Finding the computed value</h3>
 
   <p> A <a href="#specified-value"><i>specified value</i></a> can be either
    absolute (i.e., not relative to another value, as in ‘<code
@@ -641,7 +706,7 @@ <h3 id=computed><span class=secno>4.2. </span> Finding the computed value</h3>
    href="#computed-value"><i>computed value</i></a> of a property for an
    element to depend on whether the property applies to that element.
 
-  <h3 id=used><span class=secno>4.3. </span> Finding the used value</h3>
+  <h3 id=used><span class=secno>5.3. </span> Finding the used value</h3>
 
   <p> <a href="#computed-value"><i>Computed values</i></a> are processed as
    far as possible without formatting the document. Some values, however, can
@@ -653,7 +718,7 @@ <h3 id=used><span class=secno>4.3. </span> Finding the used value</h3>
    href="#computed-value"><i>computed value</i></a> and resolving any
    remaining dependencies into an absolute value.
 
-  <h3 id=actual><span class=secno>4.4. </span> Finding the actual value</h3>
+  <h3 id=actual><span class=secno>5.4. </span> Finding the actual value</h3>
 
   <p> A <a href="#used-value"><i>used value</i></a> is in principle ready to
    be used, but a user agent may not be able to make use of the value in a
@@ -674,7 +739,7 @@ <h3 id=actual><span class=secno>4.4. </span> Finding the actual value</h3>
    reflect how many orphan lines there is in a certain element. See examples
    (j) and (k) in the <a href="#stages-examples">table below</a>.
 
-  <h3 id=stages-examples><span class=secno>4.5. </span> Examples</h3>
+  <h3 id=stages-examples><span class=secno>5.5. </span> Examples</h3>
 
   <table class=data>
    <thead>
@@ -868,7 +933,7 @@ <h3 id=stages-examples><span class=secno>4.5. </span> Examples</h3>
      <td>‘<code class=css>3</code>’
   </table>
 
-  <h2 id=conformance><span class=secno>5. </span>Conformance</h2>
+  <h2 id=conformance><span class=secno>6. </span>Conformance</h2>
 
   <p>[TBD]
 
@@ -981,13 +1046,13 @@ <h2 class=no-num id=index>Index</h2>
 
   <ul class=indexlist>
    <li>actual value, <a href="#actual-value"
-    title="actual value"><strong>4.4.</strong></a>
+    title="actual value"><strong>5.4.</strong></a>
 
    <li>cascaded value, <a href="#cascaded-value0"
-    title="cascaded value"><strong>3.2.4.</strong></a>
+    title="cascaded value"><strong>4.2.4.</strong></a>
 
    <li>computed value, <a href="#computed-value"
-    title="computed value"><strong>4.2.</strong></a>
+    title="computed value"><strong>5.2.</strong></a>
 
    <li>conditional import, <a href="#conditional-imports"
     title="conditional import"><strong>2.</strong></a>
@@ -996,28 +1061,31 @@ <h2 class=no-num id=index>Index</h2>
     href="#atimport" title="''@import''"><strong>2.</strong></a>
 
    <li>inherited properties, <a href="#inherited-properties"
-    title="inherited properties"><strong>3.3.2.</strong></a>
+    title="inherited properties"><strong>4.3.2.</strong></a>
 
    <li>inherited property, <a href="#inherited-properties"
-    title="inherited property"><strong>3.3.2.</strong></a>
+    title="inherited property"><strong>4.3.2.</strong></a>
 
    <li>inherited value, <a href="#inherited-value"
-    title="inherited value"><strong>3.3.2.</strong></a>
+    title="inherited value"><strong>4.3.2.</strong></a>
 
    <li>initial value, <a href="#initial-value"
-    title="initial value"><strong>3.3.1.</strong></a>
+    title="initial value"><strong>4.3.1.</strong></a>
 
    <li>media-dependent import, <a href="#conditional-imports"
     title="media-dependent import"><strong>2.</strong></a>
 
    <li>output of the cascade, <a href="#output-of-the-cascade"
-    title="output of the cascade"><strong>3.2.</strong></a>
+    title="output of the cascade"><strong>4.2.</strong></a>
+
+   <li>shorthand properties, <a href="#shorthand-properties"
+    title="shorthand properties"><strong>3.</strong></a>
 
    <li>specified value, <a href="#specified-value"
-    title="specified value"><strong>4.1.</strong></a>
+    title="specified value"><strong>5.1.</strong></a>
 
    <li>used value, <a href="#used-value"
-    title="used value"><strong>4.3.</strong></a>
+    title="used value"><strong>5.3.</strong></a>
   </ul>
   <!--end-index-->