[selectors] Address anne's comments.

Author: tabatkins

selectors/Overview.bs

@@ -20,7 +20,7 @@ Abstract: <b>Selectors</b> are patterns that match against elements in a tree, a
 Abstract: Selectors Level 4 describes the selectors that already exist in [[!SELECT]], and further introduces new selectors for CSS and other languages that may need them.
 At Risk: the column combinator
 At Risk: The '':drop()'' pseudo-class
-Ignored Terms: DocumentFragment, math, h1, host element, shadow tree, box tree
+Ignored Terms: DocumentFragment, math, h1, shadow tree, box tree, query()
 Link Defaults: html5 (element) a
 </pre>
 <style>
@@ -79,7 +79,7 @@ Selectors Overview</h2>
 	<em>This section is non-normative, as it merely summarizes the
 	following sections.</em>
 
-	A Selector represents a structure. This structure can be used as a
+	A selector represents a structure. This structure can be used as a
 	condition (e.g. in a CSS rule) that determines which elements a
 	selector matches in the document tree, or as a flat description of the
 	HTML or XML fragment corresponding to that structure.
@@ -506,7 +506,7 @@ Selectors Overview</h2>
 		<dt><dfn id='complete-profile'>complete</dfn>
 		<dd>
 			The <a>complete</a> profile is appropriate for contexts which aren't extremely performance sensitive.
-			For example, implementations of the Selectors API specification [[SELECTORS-API]] should use the ''complete'' profile.
+			For example, the <a method for=Element>query()</a> method defined in [[DOM]] should use the ''complete'' profile.
 			It includes all of the selectors defined in this document.
 	</dl>
 
@@ -530,16 +530,15 @@ Structure and Terminology</h3>
 	A <a>selector list</a> is a comma-separated list of <a>selectors</a>;
 	see <a href="#grouping">Selector Lists</a>.
 
-	A <dfn id="complex" export>complex selector</dfn> is a chain of one
-	or more <a>compound selectors</a>
+	A <dfn id="complex" export>complex selector</dfn> is a sequence of one or more <a>compound selectors</a>
 	separated by <a>combinators</a>.
 
 	A <dfn id="compound" export>compound selector</dfn>
-	is a chain of <a>simple selectors</a>
-	that are not separated by a <a>combinator</a>. It
-	always begins with a <a>type selector</a> or a
-	(possibly implied) <a>universal selector</a>.
-	No other type selector or universal selector is allowed in the sequence.
+	is a sequence of <a>simple selectors</a>
+	that are not separated by a <a>combinator</a>.
+	If it contains a <a>type selector</a> or <a>universal selector</a>,
+	that selector comes first in the sequence.
+	Only one type selector or universal selector is allowed in the sequence.
 
 	A <dfn id="simple" export>simple selector</dfn> is either a
 	<a>type selector</a>,
@@ -549,20 +548,24 @@ Structure and Terminology</h3>
 	<a>ID selector</a>,
 	or <a>pseudo-class</a>.
 
-	A <dfn export>combinator</dfn> is punctuation that represents a particular
-	kind of relationship between the <a>compound selectors</a> on either side.
+	A <dfn export>combinator</dfn> represents a particular kind of relationship
+	between the <a>compound selectors</a> on either side.
 	Combinators in Selectors level 4 include:
 	whitespace,
 	“greater-than sign” (U+003E, <code>></code>),
 	“plus sign” (U+002B, <code>+</code>),
 	and “tilde” (U+007E, <code>~</code>).
-	<a href="#whitespace">White space</a> may appear between a combinator
-	and the simple selectors around it.
+
+	Issue: Fill in more combinators.
 
 	An empty selector,
 	containing no <a>compound selector</a>,
 	is an <a href="#invalid">invalid selector</a>.
 
+	Note: As whitespace is a valid <a>combinator</a>,
+	no whitespace is allowed between the <a>simple selectors</a>
+	in a <a>compound selector</a>.
+
 <h3 id='evaluating-selectors'>
 Evaluating a Selector</h3>
 
@@ -656,8 +659,7 @@ Evaluating a Selector</h3>
 	must define the <dfn export>initial selector match list</dfn>,
 	the list of elements that every selector in that context begins with.
 
-	For HTML,
-	when evaluating a selector against a document,
+	When evaluating a selector against a DOM document,
 	the <a>initial selector match list</a>
 	is the root element and all of its descendants,
 	ordered by a pre-order traversal.
@@ -671,13 +673,13 @@ Evaluating a Selector</h3>
 <h3 id='data-model'>
 Data Model</h3>
 
-	Selectors are matched against an <dfn export>element tree</dfn>,
-	which is an abstract tree structure consisting of elements.
+	Selectors are matched against a <a>selector match list</a> of elements,
+	which is usually arranged in an abstract tree structure.
 
 	Each element may have any of:
 
 	<ul>
-		<li>A type, which is a string.
+		<li>A type, which is a pair of strings: a namespace and a local name.
 		<li>An ID, which is a string.
 		<li>Classes, which are strings.
 		<li>Attributes, which are pairs of strings consisting of an attribute name and an attribute value.
@@ -704,14 +706,14 @@ Data Model</h3>
 	(For example, the <a>host element</a> in a <a>shadow tree</a> is <a>featureless</a>,
 	and can't be matched by <em>any</em> <a>pseudo-class</a> except for '':host'' and '':host-context()''.)
 
-	In HTML,
-	the DOM is used as the <a>element tree</a>.
-	Each DOM element is an element in the <a>element tree</a>,
+	In a DOM document,
+	the DOM is used as the <a>selector match list</a>.
+	Each DOM element is an element in the <a>selector match list</a>,
 	with the DOM element's tagname as the type,
 	and its ID, class list, attributes, and child elements
-	as the ID, classes, attributes, and child elements in the <a>element tree</a>.
+	as the ID, classes, attributes, and child elements in the <a>selector match list</a>.
 	The rest of the information in the DOM is also accessible
-	as the arbitrary additional information in the <a>element tree</a>.
+	as the arbitrary additional information in the <a>selector match list</a>.
 
 
 <h3 id="scoping">
@@ -743,7 +745,7 @@ Scoped Selectors</h3>
 
 	<div class='example'>
 		For example,
-		the <code>element.querySelector()</code> function defined in [[SELECTORS-API2]]
+		the <code>element.querySelector()</code> function defined in [[DOM]]
 		allows the author to define a <a>scope-filtered</a> selector.
 
 		On the other hand, the selectors within an [[HTML5]] scoped stylesheet
@@ -810,15 +812,6 @@ Absolutizing a Relative Selector</h4>
 			Otherwise, the selector is already absolute.
 	</ol>
 
-	<p class='issue'>
-		The above algorithm is different from Selectors API: its step 2, which bailed if there were no :scope elements, has been removed.
-		This is because handling an explicitly empty list should return nothing;
-		if no :scope elements were given at all,
-		Selectors API 2 should be amended to say that the selector must be absolute already.
-		(Broken example: doing <code>document.query('img', [list-of-links]))</code> finds images that are descendants of links normally,
-		but instead finds all images in the document if the list-of-links is empty.)
-
-
 	To <dfn id='absolutize-list' export>absolutize a relative selector list</dfn>,
 	absolutize each relative selector in the list.
 
@@ -934,7 +927,7 @@ Pseudo-classes</h3>
 	<a>Pseudo-elements</a> may have children,
 	as defined by the specification defining them.
 	Their children can be children of other elements, too,
-	turning the <a>element tree</a> into a directed acyclic graph,
+	turning the <a>selector match list</a> into a directed acyclic graph,
 	but their rendering must be defined so as to maintain the tree-ness of the <a>box tree</a>.
 
 	<div class='example'>
@@ -2106,7 +2099,7 @@ The reference element pseudo-class '':scope''</h3>
 	In some contexts, selectors can be matched with an explicit set of <dfn dfn export title=":scope element">:scope elements</dfn>.
 	This is is a (potentially empty) set of elements
 	that provide a reference point for selectors to match against,
-	such as that specified by the <code>querySelector()</code> call in [[SELECTORS-API2]],
+	such as that specified by the <code>querySelector()</code> call in [[DOM]],
 	or the parent element of a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-style-element">scoped <code>&lt;style></code> element</a> in [[HTML5]].
 
 	The <dfn id='scope-pseudo'>:scope</dfn> pseudo-class represents any element that is a <a>:scope element</a>.
@@ -2150,6 +2143,11 @@ User Action Pseudo-classes</h2>
 		the pseudo-class :focus and in the pseudo-class :hover.
 	</div>
 
+	Note: The specifics of hit-testing,
+	necessary to know when several of the pseudo-classes defined in this section apply,
+	are not yet defined,
+	but should be in the future.
+
 <h3 id="the-hover-pseudo">
 The pointer hover pseudo-class '':hover''</h3>
 
@@ -2525,19 +2523,23 @@ Tree-Structural pseudo-classes</h2>
 '':root'' pseudo-class</h3>
 
 	The <dfn id='root-pseudo'>:root</dfn> pseudo-class represents an element that is
-	the root of the document. In HTML 4, this is always the
-	<a element>HTML</a> element.
+	the root of the document.
+
+	For example, in a DOM document,
+	the '':root'' pseudo-class matches the root element of the <a interface>Document</a> object.
+	In HTML, this would be the <a element>html</a> element
+	(unless scripting has been used to modify the document).
 
 <h3 id="the-empty-pseudo">
 '':empty'' pseudo-class</h3>
 
-	The <dfn id='empty-pseudo'>:empty</dfn> pseudo-class represents an element that has
-	no children at all. In terms of the document tree, only element nodes and
-	content nodes (such as DOM [[DOM-LEVEL-3-CORE]] text nodes, CDATA
-	nodes, and entity references) whose data has a non-zero length must be
-	considered as affecting emptiness;
-	comments, processing instructions, and other nodes must not affect whether
-	an element is considered empty or not.
+	The <dfn id='empty-pseudo'>:empty</dfn> pseudo-class represents an element that has no children at all.
+	In terms of the document tree,
+	only element nodes and content nodes
+	(such as [[DOM]] text nodes, and entity references)
+	whose data has a non-zero length must be considered as affecting emptiness;
+	comments, processing instructions, and other nodes
+	must not affect whether an element is considered empty or not.
 
 	<div class="example">
 		Examples: