Systematic faults in normative presentation of content models (ODF 1.2 CD01)

["Alex Brown" <alexb@griffinbrown.co.uk>]

Dear all,

The presentation of elements (currently the monospaced text on a
peach-coloured background) within ODF 1.2 CD01 is a big step backward
from previous versions, and needs to be revisited.

Consider the first time this happens, in 2.2.2

----b
The <office:document> element is a root element.
The <office:document> element may be used with the following elements:
<db:component> 11.3.5 and <draw:object> 9.4.5.2.
The <office:document> element may have the following attributes:
grddl:transformation 18.327, office:mimetype 18.382 and office:version
18.392.
The <office:document> element may have the following child elements:
<office:automatic-styles> 2.16.3, <office:body> 2.4,
<office:font-face-decls> 2.15, <office:master-styles> 2.16.4,
<office:meta> 2.3, <office:scripts> 2.13, <office:settings> 2.11 and
<office:styles> 2.16.2.
----e

The problems with this are:

1. It is verbose and very difficult to read. Later in the spec we have
whole half-pages containing solid blocks of similar content. 

2. It is casually worded to the point of being meaningless: what does it
mean that an element "may be used with" another element, e.g.?

3. It contradicts the schema. The text above says this element *may*
have the office:mimetype attribute, yet the schema declares this element
*shall* have this attribute. Similarly, it is stated above that the
element *may* have certain children element which, according to the
schema, are mandatory. A consequence of this systematic fault is that a
large portion of the normative content of this draft is, simply,
*wrong*.

Any normative statement of an element's grammar (which is what this is)
should be made using a clear, terse, and unambiguous notation. SC 34 has
standardised RELAX NG compact syntax expressly for this purpose.

The ODF spec should be re-written to use RNG compact syntax to express
the normative content models of XML elements. This RNG should be
part-normalized to eliminate opaque patterns and bring actual element
and attribute declarations to the fore. Ideally each mentioned
element/attribute name should then be hyperlinked to its corresponding
description in the spec.

- Alex.