Selectors

Firstly, :contains is not a pseudo-class. Next:

 ':contains ... represents a substring of ... an element'

Presumably this is 'substring or substrings'? If so, how might one match
the first 'W' in <menu><item>File</item><item>Window</item></menu>?

Furthermore, I presume the selector is intended to be case-sensitive;
however, since the
general rule for CSS is that CSS is *not* case-sensitive, an explicit
statement to the effect that it is necessary; if it is not, a statement
is also necessary because one would presume the contrary.

An incidental missing apostrophe:

'Pseudo-elements names are case-insensitive.'

Also, it would be useful if the proposal addressed some of the known
ambiguities with the current selectors specification (these are off the
top of my head - I might have missed some of them):

'The :first-line pseudo-element describes the first formatted line of a
paragraph.'

This leads one to think that one is selecting the formatted text, but in
fact the pseudo-element selects the text that forms the first formatted
line. So I suggest changing this to:

'The :first-line pseudo-element selects the characters in the source
that form the first
formatted line of a paragraph. For example, given the following element:

<p>
Some example text spanning more than one line.
</p>

assuming that the rendering is as follows:

Some example text spanning
more than one line.

P:first-line {vertical-align: super} is precisely equivalent to:

<p>
<span style="vertical-align: super">Some example text spanning</span>
more than one line.
</p>

Also:

'The :first-line pseudo-element is similar to an inline-level element,
but with certain
restrictions, depending on usage.'

Where are these enumerated? In individual modules? (I suggest not; they
should be listed
here.)

Further:

'The :first-letter pseudo-element describes the first formetted letter
of a paragraph
The :first-letter pseudo-element is similar to an inline-level element
if its CSS 'float' property is 'none', but with certain restrictions,
depending on usage.'

The most obviously defect here is the 'formetted' and the missing '.',
but I would also argue that the sentence should be changed, as before,
to:

'The :first-letter pseudo-element selects the first character in the
element.' (*Not* paragraph - :first-letter applies to inline-level
elements too.

Furthermore, 'is similar to an inline-level element if' [float: none]
implies something that isn't true. It is the same as an inline-level
element (such as SPAN or B), except there are restrictions as to the
properties that apply to it.'

'The :before and :after pseudo-elements

The :before and :after pseudo-elements can be used to describe generated
content before or after an element's content.

When the :first-letter and :first-line pseudo-elements are combined with
:before and :after, they apply to the first letter or line of the
element including the inserted text.'

Here are some suggestions:

Add after the first sentence: 'Note that although these selectors are
called :before and :after, to a certain extent this is a misnomer,
because the content is not inserted before the element, but instead
before the element's content. For example, SPAN:before {content:
"Hello"} with <span>Content</span> is equivalent to
<span>HelloContent</span>, rather than Hello<span>Content</span>.
Similarly, P:before {display: block; content: "Content"} would be
covered by the border of P {border: solid}. The blocks would be
generated as follows:

<p block box>
<:before block box>
Content
</:before>
<anonymous block box>
Rest of p
</p>'

And the second sentence isn't very clear at all. I would suggest instead
'Since :before and :after are 'inside' the element, :first-letter and
:first-line select the text accordingly. For example, :before#elem
{content: "Hello"; display: block} :first-line#elem {color: red} and
<div id="elem">Content</div> would make 'Hello' red.'

Another thing that needs clarifying is whether LI:first-line and
LI:first-letter select the marker box, since user agents vary in their
implementations. I'm not sure - it seems a special case:

LI {margin-left: 5%}
LI:before {display: marker /* Equivalent to display: list-item */;
content: counter(counter) ".";
counter-increment: counter}

Now given:
<li>
</li>

we have:

<li block box>
<:before block box inside li block box>
</:before>
<anonymous>
</li>

It should be apparent here that we have a problem: marker boxes are
placed to the left (in ltr environments anyway) of the border edge of
the principal block boxes. But by analysing the boxes that we have
generated (although CSS2 does not mention it, it is necessary that
:before and :after actually mean 'inside' - otherwise you would get
results such as 'beforetext<p>inside text' (i.e., the text would be
placed above the element!), which is clearly absurd) we see there is a
problem. CSS2 states:

'While 'block' and 'inline' :before and :after content is part of the
principal box generated by the element, 'marker' content is formatted in
an independent marker box, outside the principal box.'

which isn't consistent with :before, which is necessarily inside the
principal block box, and affected by such things as padding and borders.
Conclusion: 'display: marker' on :before and :after are a special case.
So refine my previous statement to:

'Note that although these selectors are called :before and :after, to a
certain extent this is a misnomer, because the content is not inserted
before the element, but instead before the element's content. For
example, SPAN:before {content: "Hello"} with <span>Content</span> is
equivalent to <span>HelloContent</span>, rather than
Hello<span>Content</span>. Similarly, P:before {display: block; content:
"Content"} would be covered by the border of P {border: solid}. The
blocks would be generated as follows:

<p block box>
<:before block box>
Content
</:before>
<anonymous block box>
Rest of p
</p>

However, 'display: marker' is a special case, actually placed before or
after the element. This means that selectors such as LI:first-letter
{color: red} do not color the marker box.'

Another thing is now that of multiple pseudo-elements: the proposal
doesn't explain what the result is.

Furthermore, the descriptions for these 'old selectors' are currently
extremely terse and need examples.

Another thing is that the text explaining one of the adjacent sibling
examples is somewhat misleading:

'Thus, the following selector represents a P element immediately
following a MATH element:'

It leads one to think that

<MATH>
</MATH>
Text
<P>
</P>

is not matched. So it should be changed to 'Thus, the following selector
matches a P element that follows the MATH element in the document tree,
and is on the same level as it. It matches both:
<MATH>
</MATH>
Text
<P>
</P>

and:

<MATH>
</MATH>
Text
<P>
</P>

but not:
<MATH>
<P>
</P>
</MATH>'

Incidental errors:

'This modularization, and the externalization of the general syntax, of
CSS will reduce the size of the spec and allow new types of
specifications to use selectors and/or CSS general syntax. For instance
behaviours or tree transformations.'

In American, that is spelt that 'behaviors'.

'It always begin with a type selector or a universal selector.'

should be 'begins'

'A pseudo-class always contains a colon (:) followed by the name of the
pseudo-class and
optionnally by a value between parenthesis.'

'optionally' and 'parentheses'

'When parsing XML, UAs do not always read the DTD, and thus may not know
what the ID of
an element is.'

'may' should be 'might'.

'Dynamic pseudo-classes may be dynamic,'

see above

Regarding :target, I would like to see :local, matching a specifically
local link (i.e., href="#any" instead of href="any.html#any"); I know
this is something I often would like to select.