Re: [chairs] New rule on which document wins when there is ambiguity

[Eduardo Gutentag <Eduardo.Gutentag@Sun.COM>]

Adding to Robin's explanation: you need to look at the context in
which this rule was formulated.

A paragraph before the one containing the rule in question stated
that a TC must produce more than one version of a specification, and
one of those versions must be declared to be the authoritative one.

At the same time, another paragraph stated that all normative
computer language definitions must also be produced separately in
plain text files.

The motivation for this last was to ensure that it was possible to
(a) prove that the schema [fragment] was well formed and valid,
as required, and (b) for implementors to copy and paste the schema
[fragment] as needed into their implementation, neither of which
would have been trivial, or perhaps even possible, in the case of
line numbered PDF versions of a specification.

There was an obvious tension between this last and the fact that
the authoritative version was the one declared by the TC to be so,
which could give rise to serious problems, as when the plain text
version said one thing and the PDF version said something different,
perhaps not well formed, and yet that was the authoritative version.

The solution to this quandary was to say that while the TC could
declare a line-numbered PDF version, for instance, to contain the
authoritative text of the specification, when it comes to those
parts of the specification that are "normative computer language
definitions" (e.g. schemas, instances, code) in all cases the
corresponding text file is the authoritative one.

Now, it's clear that the rule is not perfect -- no rule is perfect.
But let's not muddy the waters here. As with any other rule a million
scenarios can be imagined in which the rule may be misinterpreted
or applied erroneously, or in which the rule is not sufficient;
one of these is the one raised by Matthew where you'd have a PDF
spec, an XSD schema and a RELAX NG schema that contradicts the XSD
schema. Well, I don't think a rule can be written that would cover
this case, except a meta-rule: All TCs should make darn sure they
read and edit carefully what they produce, and make sure that what
they produce is implementable.

Regarding Chris's objection, please note that this rule is intended
to deal only with definitions (as in "normative computer language
definitions", i.e. schema fragments, for instance) that may not say
the same in the case of the PDF and the text only file, not with
rules specified in the text of the specification. If there is a
case in which the spec says that the element name is "foo" and the
fragment embedded in the spec says the element name is "foo", and
a text file is pointed at from there in which the element name is
"bar", well -- I would point out the meta-rule above...But if the
issue is that the spec specifies schematron-like constraints and the
schema fragment in the text file cannot express those constraints,
I bet you the schema fragment in the spec cannot express them either,
so there is no conflict, is there?

Finally, regarding Kelvin comments: the rule does not say that
when there is a discrepancy between a normative specification and
and external document the external document prevails. What it says
is that when there is a discrepancy between a normative computer
language definition in the specification and its equivalent normative
computer language definition in the external document, the external
document should be considered the authoritative one.

Perhaps that paragraph should be rewritten, abandoning the desire
for elegant language in favor of a clearly unambiguous expression:

"All normative computer language definitions that are part of the
specification, such as XML instances, schemas and Java(TM) code,
including fragments of such, must be well-formed and valid, and
must be provided in separate plain text files. Each text file must
be referenced from the specification. Where any computer language
definition in these separate files disagrees with the corresponding
computer language definition found in the specification, the computer
language definition found in the separate plain text file is the
authoritative one."

Would that lower your concerns?

PS - another way to write the meta-rule above would be "TCs are
not allowed to be ridiculously sloppy" ;-)


On 08/08/2009 08:16 AM, Matthew Dovey wrote:
>> In summary: the notion of precedence introduced by the word "prevails"
>> was NOT, as I recall, intended to address the matter of (apparent discrepancy
>> and) highest authority in cases where (e.g.,):
>>
>> a) an assertion in prose (embodied in the main prose document
>>     which is part of a specification) conflicts, or apparently
>>     conflicts with an assertion based upon declarations in
>>     a W3C XML schema file, RNG schema, DTD, Schematron schema, or
>>     other machine-readable text with computer language definitions
> 
> <snip>
> 
>> c) one kind of formal language description embedded, as
>>     display text, in the main prose document (part) of a
>>     specification conflicts with assertions made by a
>>     DIFFERENT kind of formal language description carried
>>     in a plain text (machine-readable) file that is also part
>>     of the specification [e.g., RNG schema in the prose is in conflict
>>     with a separate W3C XML Schema file definition]
>>
>> RATHER, the "discrepancy" envisioned in the new TC Process document
>> (sentence containing "the separate file prevails") and mentioned in Mary
>> McRae's announcement [2] is simply a situation arising from human editing
>> error and/or machine conversion error, where the TC's intent is to include
>> the SAME machine-readable formal language definition text in BOTH:
>>
>> [i]  separate plain-text file, for use mainly by machines [ii] the main prose
>> specification document, as display text,
>>       for use mainly by human readers
>>
>> Viz., the intent was that the text characters be identical (modulo white space
>> allowable for a particular formal language representation) in BOTH [i] and [ii],
>> but it's discovered that by error, some textual difference has crept in, and it
>> was undetected at publication time.
> 
> If the error is purely presentational, then I'm not convinced that there is a significant problem which warrants its own dedicated OASIS rule.  On the other hand if an error of the above form is not purely presentational, then it causes either the machine readable file to be syntactically incorrect for the machine parsers - although this should be detected and fixed by the sorts of tools Toby refered, or the two situations (a) and (c) above. When the error (however caused or overlooked) causes cases (a) and (c) above, then determining the corrective course of action involves weighing up the consequences to existing implementations if the error were fixed to be what was intended, against the consequences as regards the consequences on the internal consistency if the error is accommodated in the specification. That decision depends very much on the context and circumstances and can't be determined by a hard and fast generic rule.
> 
> Matthew
> 
> 
> 

-- 
Eduardo Gutentag        |    e-mail: eduardo.gutentag@Sun.COM
Technology Director     |    Phone:  +1 510 550 4616 (internal x31442)
Corporate Standards     |    Sun Microsystems Inc.
              W3C AC Rep / W3C AB / OASIS BoD