Re: [office-comment] Systematic faults in normative presentationof content models (ODF 1.2 CD01)

[Patrick Durusau <patrick@durusau.net>]

Alex,

Sorry, I have been offline for several days due to illness.

Alex Brown wrote:
> 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.
>
>   
If you had stopped to consider the content of the material in question 
you would have realized that it is in fact *is*

"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."

I agree that the mandatory/optional nature of the models should be 
reflected in the auto-generated language and that plus the nature of 
auto-generated value lists for attributes with enumerated values is 
already underway.

Since the RELAX NG schema will be a normative part of the standard, I 
fail to see why we should include a form of it here. A "part-normalized" 
form is going to be as long as what you complain about here, assuming we 
insert the hyperlinked references. Moreover, the standard would then 
fact the objection that it was *duplicating normative content.* An 
objection many would find persuasive. As it stands, we are simply 
providing relevant cross-references that aid in understanding a 
particular element or attribute.

Recall that there are issues with the structure of the schema that are 
directly related to its early editorial use and I would prefer to avoid 
those in the future. Structures for schema authoring should facilitate 
that task and no other.

Hope you are at the start of a great week!

Patrick


> 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.
>
>
>   

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)