RE: [office-comment] Unacceptable presentation of content models (ODF 1.2CD01r5)

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

Dear Michael, all,

> Michael Brauer wrote:
> On 04/14/09 22:10, Alex Brown wrote:
> > Dear all,
> > 
> > I have just taken a quick look at the new (rev5) draft of 1.2.
> > 
> > The presentation of content models (text on a peach background) is
still
> > completely unacceptable, and this draft is consequently still mostly
one
> > enormous defect.
> > 
> > For the spec say (as it does) "the element [x] is usable used with
the
> > following elements" makes no sense. And assuming you delete the
spurious
> > word 'usable' the statement is still way too loose and casual for a
> > normative statement of an element's "upward" content model, since
there
> > will be constraints upon how that element's parent may come to
contain
> > the element in question as a child.
> 
> Yes, there are additional constrains. These can be found in the
schema. 
> And because these cannot be expressed reasonably in a natural
language, 
> we are not using any normative words here.

This *is* normative text. And normative text is meant to express clear,
testable statements. I agree it's not sensible to try and express these
things precisely in natural language. But as it is this text is wrongly
defining what implementers can point to and proclaim is conformant.

> The natural language we are using here has the purpose of providing 
> cross references. The purpose is neither to normatively define any 
> constrains, nor to duplicate what is said already in the schema.

Well, in that case mark these things as notes (or some other form of
informative text) and remove the misleading wording which implies that
these things are defining content models. I don't know, try something
_like_: 

"In valid instances this element shall have a location such that:

- it has one of these parent elements [list]

- its child elements are not outside the set of [list]

- its attributes are not outside the set of [list]"

By making the text informative, there would be no danger of anybody
treating these as faux content models. Also, such wording is technically
correct.
 
> > The draft also states throughout that "The [x] element has the
following
> > child element(s)". But in *reality* your content models allow
choice,
> > sequencing, grouping, etc. But you have invented a prose schema
language
> > which loses all this vital information and lossily dumbs it down.
> > 
> > This is a serious systematic fault in this draft and fiddling around
> > with the wording is not going to cure it: you need to find an
accurate
> > and lossless way to represent the content models of elements you are
> > normatively describing - and just such a thing already exists in RNG
> > compact syntax.
> 
> This does also exist in the RNG schema that belongs to the
specification 
> and will become part of the standard. One may embed the schema into
the 
> specification document as we did in ODF 1.0/1.1, but this has some 
> disadvantages, too. The most serious one is that the structure of the 
> specification has to follow the schema, or vice versa.

Well, that is a consequence of having the rule that joining the
fragments together will reconstitute the schema.

It is perfectly possible (but a bit of work) to simplify/normalize the
schema programatically and generate pretty-printed RNG compact syntax
fragments which represent patterns for the elements/attributes you are
describing. The names can also be hyperlinked to their relevant
descriptions elsewhere in the spec. This would be more accurate, more
readable and generally more compact than the present approach.

- Alex.