The following information is to help ARIA editors ensure that the specifications use the technical structure required by the automated QA suite. This information is currently out of date because the specifications are being changed to a new format, relying on Respec instead of XSLT to present the final output. Once that change is complete, the guidance here will be updated.
The ARIA documents need to be in valid XHTML. Their life as XML allows XSLT-based processing.
The XSLT keys in many cases off special class attribute values, which need to be used in certain ways. These special classes are documeted below. Some of these classes are also used for visual styling, but not all are. All these classes are defined in the CSS stylesheet, however, in order to make them available to the authoring tool interface.
Each section should be enclosed in a <div class="section"> (referred to here as "section divs"). Sub-sections should be in nested section divs. All sections will then have the same number of ancestor section divs as the number of points in their heading number, e.g., a heading of #.#.# will be three section divs deep.
The first child of a section div should be a named anchor identifying that section. A named anchor should have both a name and id attribute, with the same value. This anchor identifies the section, and therefore there is no need to have an id on the section div itself, nor on the heading. This structure is for XSLT convenience and is permitted by pubrules.
The second child should be the heading element. It doesn't matter what level the heading is, as the XSLT will adjust it to the appropriate level based on the depth of the section div. If the heading has three ancestor section divs, the XSLT will automatically set it to <h4> (<h1> is used for the document title, so <h2> is the starting heading level). This is done so if a section is moved, you don't have to think through the heading level (nor worry about regenerating the table of contents). As long as the section div is nested in the right place, everything else will come out right.
<div class="section">
<a name="seca" id="seca"></a>
<h2>Section 1</h2>
...content...
<div class="section">
<a name="secb" id="secb"></a>
<h3>Section 1.1</h3>
...content...
</div>
</div> These classes are used on <a> elements that reference role or state values (both internal references and cross references into the roles or states specs). There is some visual formatting, but more importantly the XSLT makes sure the link targets a correct URL. The URL of the appropriate document is provided, and the link text is used as the anchor. Therefore, when initially creating one of these links, the actual URL provided doesn't matter as long as the appropriate class value is provided, and the link text is the correct name of the role, state, or property.
<a class="role-reference" href="http://www.w3.org/TR/aria-role/#example">example</a>
This is provided in a <span> around the number at the beginning of each numbered heading inside a section div. This is used partly to differentiate the number from the rest of the heading, so only the heading text is extracted for the TOC. It's also the place into which the number is generated, based on the position of the section div. It is not necessary to provide this on new headings, as the XSLT will add it the first time it goes through; this is just to be aware that it's there and why. Note that there should be a space after the closing </span> and the start of the rest of the heading.
<h3><span class="tocnum">1.1</span> Section heading</h3>
These are provided on <div> elements. They are much like section divs, but identify individual role and state documentation. Like section divs, there should be a named anchor, followed by a heading (with a class of "role-name" or "state-name"). Like section divs, the heading level will be automatically adjusted, but instead of a numbered heading, a "role" or "state" prefix is used.
Note that within these, there are lots of classes used that are purely for XSLT automation. Since everything is in place, there shouldn't be a need to document the details.
This is used on the list elements in the table of contents. The list with this class is where the TOC will be updated to.
This is used on the <h2> that indicates the W3C document status. This allows the publication date to be automatically updated to the date the XSLT was run.
Notes to us to get back to something are marked with the "todo" class. This can be on any element, e.g., a <p>, and can be on a <span> wrapped around a phrase if no other element suits. In addition to making these visible and easy to find, these are stripped out of the document wholesale before going to TR, on the basis of this class name. Note that any todo should also start with "Todo: " for accessibility reasons.