Bug 24756 - [imports]: Cascading order for stylesheets of imported documents should be stated more clearly

Add some clarification and an informative section.

Author: omo

assets/images/import-style-document-order.png

@@ -487,7 +487,28 @@ <h2 id="style-imports">Style processing with Imports</h2>
 the external resources of the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#the-link-element">link</a></code> elements in <a href="#dfn-import">imports</a> <strong>must</strong> be considered as input sources of the <a href="http://www.w3.org/TR/CSS21/intro.html#processing-model">style processing model</a> of the <a href="#dfn-master-document">master document</a>.</p>
 
 <div class="fixme">
-<p>Between declarations from different documents, the document order in terms of <a href="http://www.w3.org/TR/css3-cascade/#cascade-order">order of appearance</a> is defined based on the document order of the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-link-element">link</a></code> elements of their <a href="#dfn-import-referrer-ancestor">import referrer ancestors</a> which are in the same document. If there are more than one of such documents, the comparison result in the first document, in the document order, wins.</p>
+<p>Between declarations from different documents, the document order in terms of <a href="http://www.w3.org/TR/css3-cascade/#cascade-order">order of appearance</a> is defined by comparing two elements <var>x</var>, whose owner document is <var>Dx</var>, and <var>y</var>, whose owner document is <var>Dy</var>, as follows:</p>
+
+<ul>
+  <li>If there is a document <var>Da</var> which is a common <a href="#dfn-import-referrer-ancestor">import referrer ancestor</a> of both <var>Dx</var> and <var>Dy</var>, use the document order order of <var>Lx</var>, the first import <code>link</code> element in <var>Da</var> that links to <var>Dx</var> or <var>Dx</var>'s <a href="#dfn-import-referrer-ancestor">import referrer ancestor</a>, and <var>Ly</var>, a <code>link</code> that imports <var>Dy</var> respectivly. The <var>x</var> element wins if <var>Lx</var> wins, or <var>y</var> wins otehrwise.
+
+  <li>If <var>Dx</var> is a <a href="#dfn-import-referrer-ancestor">import referrer ancestor</a> of <var>Dy</var>, compare the document order of <var>x</var> and a <var>Ly</var>, the first import <code>link</code> in <var>Dx</var> which links to <var>Dy</var> or <var>Dy</var>'s <a href="#dfn-import-referrer-ancestor">import referrer ancestor</a>. If <var>x</var> wins over <var>Ly</var> it wins over <var>y</var> as well.
+
+  <li>If <var>Dy</var> is a <a href="#dfn-import-referrer-ancestor">import referrer ancestor</a> of <var>Dx</var>, compare the document order of <var>y</var> and a <var>Lx</var> respectivly.
+</ul>
+
+<div class="informative">
+<p>Here is an illustrative document order of an import tree.</p>
+<p>In this example, the master document has two <var>link</var> elements which import <var>B</var>'s <a href="#dfn-import-referrer-ancestor">import referrer ancestors</a>. When comparing <var>b1</var> and <var>m2</var>, <var>b1</var> wins over <var>m2</var> because the first <code>link</code>, which is used to the comparison, appears before <var>m2</var> in the master document.</code></p>
+
+  <img src="../../assets/images/import-style-document-order.png">
+  <figcaption>
+    An example of document order of styles in different documents in an import tree.
+  </figcaption>
+
+<p>The comparison uses the notion of <a href="#dfn-import-referrer-ancestor">import referrer ancestors</a> instead of <a href="#dfn-import-import-ancestor">import ancestor</a>. This implies that moving import <code>link</code> through DOM mutation affect the ordering. It follows how <code>style</code> elements and <code>link</code> element for stylesheets work.</p>
+</div>
+
 <p>See <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=24756">Bug 24756</a>.</p>
 </div>