Re: [office-comment] Unacceptable presentation of content models (ODF1.2CD01r5)

[Michael Brauer - Sun Germany - ham02 - Hamburg <Michael.Brauer@Sun.COM>]

Alex,

On 04/15/09 09:33, Alex Brown wrote:
> 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.

Well, that's a complex topic, and opinions differ whether a statement 
which does contain any of the keywords like shall and may is a normative 
one or not.

But you are right. It is probably worth to state somewhere in 
specification, maybe in the notation section, what the purpose of the 
element and attribute lists is.
> 
>> 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.

Thanks for these suggestion. Actually, I think the exact wording is to 
some degree also a matter of personal preferences, and I would like to 
leave it up to the TC editor to find an appropriate wording. I 
personally have an issue with using the term "shall" here as this again 
raises the question of whether this normative language or not (or why 
normative language is used in informative text).

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

Again, this is to some degree a question of personal preferences. People 
which are familiar with reading RNG in compact notation may prefer this 
notation, others may prefer RNG in XML notation, and others may prefer 
natural language even if it is not as exact as a schema fragment.

Best regards

Michael

> 
> - Alex.
> 
> 
> 
> 


-- 
Michael Brauer, Technical Architect Software Engineering
StarOffice/OpenOffice.org
Sun Microsystems GmbH             Nagelsweg 55
D-20097 Hamburg, Germany          michael.brauer@sun.com
http://sun.com/staroffice         +49 40 23646 500
http://blogs.sun.com/GullFOSS

Sitz der Gesellschaft: Sun Microsystems GmbH, Sonnenallee 1,
	   D-85551 Kirchheim-Heimstetten
Amtsgericht Muenchen: HRB 161028
Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
Vorsitzender des Aufsichtsrates: Martin Haering