Because <states> has so many child elements with similar syntax, the ideal organization for this reference entry might not necessarily be the same as for all other elements. However, it should be closer than what it currently is because the current organization is confusing. There are also other issues.
1. Move the attributes table, its intro sentence, and the following example and "for more info" to the Details section.
2. Change column heading "Render states and their child elements" to "Render states and their child elements (see "Details" for attributes).
3. Change column heading "Valid values or types, and index attribute" to "Valid value or type for value or param attribute; index attribute"
4. Change attributes table intro sentence from "Each render state – or its child elements if it has any, as shown in the render states table – has the following attributes:" to this:
" The following attributes apply to:
* Render states without child elements
* Child elements of render states (as shown in the render states table)"
5. Throughout, adjust "following table" or "preceding table" as needed (pref to "Render states table" or "Attributes table in "Details"").
6. In render states table, when there are multiple child elements, clear label values/types for each with element name (e.g., (For src:"). And remove any blank line at the top of the cell as will no longer be needed.
7. "Index" attribute name needs to be formatted like other attr names.
8. For index attr's, instead of putting "req" or "opt" in separate sentence, change to e.g., "Required index attribute...." or "Optional index attribute..."
9. Want to make the GLES and GLES2 columns just wide enough for Yes/No. So move qualifiers into Values column or turn into table footnote (for repetitive ones).
10. Not clear what "GLES2 only" etc.means in those columns; remove and put NOTE into Render states column? (or footnote) saying "valid only in GLES2 profile").
11. Use "yes" or "-" (for no) in the gles columns, which is easier to scan (and is consistent with table under <technique> (FX)).