content "select" attribute needs better documentation

[c1051]

In the 1.0 "Local DOM Basics and API, DOM distribution", the content "select" attribute is given barely a mention. The documentation was insufficient to understand how it works, and so I found myself coding by trial and error. This makes me nervous because without clear documentation, the interface contract is vague. I have no idea whether I got something to work because the functionality was intended or because of a fluke which might change.

When several content tags are present:

• What role does order have?
• If some tags have the "select" attribute and some do not, in which order are they evaluated?
• Can an element be associated with more than one content tag? (This part of the doc would be a great place to tell me how to use your vocabulary. What should I call this set of elements?)

The documentation states:

"The element supports a select attribute which filters nodes via a simple selector."

Perhaps this was better documented in earlier versions, but "simple selector" is difficult to work with. It is clearly defined in https://www.w3.org/TR/selectors/#simple-selectors and a reference would be appreciated. Yet a reference alone is insufficient because not all simple selectors described on w3.org work with the "select" attribute. For example: ":first-child" should work but doesn't; instead, I must use "*:first-child".

Examples of a few selectors and pseudo-classes would be appreciated.

[petershafer]

I'd definitely like to see more documentation around the select attribute as well.