documenting and checking style names and references

[Jos van den Oever <jos@vandenoever.info>]

The styles in ODF are pretty complex. There are many different groups of style 
names and many places from which these keys can be referenced. For example, a 
style:style element can define a style, but depending on which of the twelve 
allowed values are in the style:family attribute and in which parent element 
(office:styles/style:style, office:document-styles/office:automatic-
styles/style:style or office:document-content/office:automatic-
styles/style:style). That gives 3 times 12 is 36 different groups of style 
names already, part of which overlap.

In an attempt to make this situation more insightful for beginner and expert 
and have a tool for validating these names and references easily, I've written 
an xml file that lists the groups of style names and the places where they 
entries are defined and referenced. Here are two excerpts:

The common style definitions for the text family are defined in office:styles and 
referenced by descendant styles.
 <key name="common-text-style">
  <def>$officestyles/style:style[@style:family='text']/@style:name</def>
  <ref>$officestyles/style:style[@style:family='text']/@style:parent-style-
name</ref>
  <ref>$stylesautostyles/style:style[@style:family='text']/@style:parent-
style-name</ref>
  <ref>$contentautostyles/style:style[@style:family='text']/@style:parent-
style-name</ref>
 </key>

The styles that can be referenced in the body of the ODF are a combination of 
the styles defined in style:styles and style:automatic-styles in the current 
xml file.
 <key name="content-text-style" extends="common-text-style">
  <def>$contentautostyles/style:style[@style:family='text']/@style:name</def>
  <ref>$body//text:span/@text:style-name</ref>
  <!--....-->
 </key>

The <def> elements contain xpath expressions that form a list of strings. 
These are the defined names. No name should appear more than once. The <ref> 
elements contain xpath expressions that result in a list of references. Each 
entry in this list should occur in the list resulted from the <def>.

The variables like $officestyles are filled in depending on ODF serialization. It 
can be /office:document/office:styles or /office:document-styles/office:styles 
depending on whether the ODF is flat or zip.

The XML format makes it easy to test particular documents. The complete file is 
available in the WebODF project:
   http://gitorious.org/odfkit/webodf/trees/master/webodf/tools/refcheck

It comes with an XSLT that forms a tool for checking. In two steps , one can 
run a check. I'm using xsltproc here, but any xslt software should work.
  xsltproc bootstrap.xsl odfkeys.xml > checkkeys.xsl
  xsltproc checkkeys.xsl content.xml
Instead of content.xml, one can also test on styles.xml or on a flat xml ODF.

I hope this approach can help make the use of styles in ODF more insightful.

Cheers,
Jos