OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Normative language specification


I think there may be a misunderstanding about what is doing the conforming
here.

The statement in question is whether or not the DTDs, the XSDs, or the prose
of the Language Reference define what the conformance rules *are*, not
whether or not the TC-provided DTDs or XSDs conform to the DITA-defined
rules for DTDs (they do, and they must, and if they don't, it's a bug and
needs to be fixed, or the conformance rules need to be relaxed).

What the 1.1 spec said, and the 1.2 spec should continue to say, is that
when there is a difference between the rules defined by the DTDs and the
rules defined by the corresponding XSDs, the DTDs are taken to be the
authority.

I think we are (or have) or its propsed that we add, an additional statement
to the effect that the prose of the standard is the first and highest
authority and if either the DTDs or XSDs differ from what the prose says,
the prose is taken to be correct.

This is primarily to cover cases where a given constraint cannot be
expressed declaratively in a DTD or XSD (or whatever formal constraint
specification we happen to use), since the presumption is that all rules
will otherwise be consistently expressed.

Again, if there is a out and out conflict between what the prose says and
what the DTDs say, then there is a bug in one or the other, but until the
bug is fixed, the prosed is presumed to be correct. For example, if the
prose says "you can have zero or more foos" and the DTD requires at least
one foo, until the prose is corrected (assuming it's wrong in this example),
a document with zero foos is, by definition, a conforming document for this
particular rule.

Cheers,

E.

On 1/13/10 4:37 PM, "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote:

> Just an observation. I agree that as a matter of principle the spec
> should be normative and the DTD/XSD code should be first among the
> things that need to conform to it.
>  
> If we fail in that, however, and something in our code does not conform
> to the spec, an implementer's product must work with our code regardless
> of what the spec says. (It'll hopefully turn up no later than their
> QA/test process.) And at the same time they must reasonably expect that
> we will bring the code into conformity with the spec, but there is no
> certainty when that will happen. So they must develop to the code and to
> the spec. 
>  
> I think it's an unlikely scenario that our DTD/XSD code would not be in
> conformity, but if that does happen then it could be a dilemma for
> implementers, depending on how much impact the disconformity has on
> their implementation.
>  
> Disconformity affects everybody downstream. It has worked the other way,
> too: Microsoft put features in IE that were outside the W3C specs,
> website developers exploited features of IE that were not in conformity
> with the specs, and then to serve up those websites other browsers had
> to support those non-conformant features.
>  
>     /Bruce
> 
> 
> ________________________________
> 
> From: Ogden, Jeff [mailto:jogden@ptc.com]
> Sent: Wednesday, January 13, 2010 2:50 PM
> To: Bruce Nevin (bnevin); DITA TC
> Subject: RE: [dita] Normative language specification
> 
> 
> 
> Bruce,
> 
> 
> 
> Are you suggesting that we have a different precedence for DITA
> 1.2 or just making an observation?
> 
> 
> 
>   -Jeff
> 
> 
> 
> From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
> Sent: Tuesday, January 12, 2010 3:49 PM
> To: Ogden, Jeff; DITA TC
> Subject: RE: [dita] Normative language specification
> 
> 
> 
> This is how I read these statements: If there's a discrepancy
> between the DTD/XSD and the spec, then the DTD/XSD code is not compliant
> and must be fixed. However, for their products to work properly with the
> DTD/XSD, implementers have to be non-compliant in the same way (or might
> have to be, depending on the nature of the discrepancy). So from their
> point of view for all practical purposes the code trumps the spec while
> they wait for "a future release" (not very comforting words!) to resolve
> the discrepancy.
> 
> 
> 
>    /Bruce
> 
> 
> 
> ________________________________
> 
> From: Ogden, Jeff [mailto:jogden@ptc.com]
> Sent: Tuesday, January 12, 2010 3:17 PM
> To: DITA TC
> Subject: RE: [dita] Normative language specification
> 
> Back in the mists of time (15 December 2009) Kris and I
> got an assignment:
> 
> 
> 
> K. Eberlin and J. Ogden to check spec statements on what
> is normative to ensure that it meets this condition and suggest any
> necessary revisions.
> 
> 
> 
> There is this statement at the start of "Overview of the
> DITA 1.2 specification":
> 
> 
> 
> The DTDs and XSDs - along with the catalog files -
> define DITA markup for the DITA vocabulary modules and DITA document
> types. While the DTDs and XSDs should define the same DITA elements, the
> DTDs are normative if there is a discrepancy.
> 
> 
> 
> This may be the only statement that we need to worry
> about, but it is hard to be sure.  If anyone knows of others, please
> speak up.
> 
> 
> 
> Assuming that this is the only statement, I suggest
> leaving it as it is and where it is. And then adding a new statement
> just before the heading "Changes included in DITA 1.2" in the same
> "Overview of the DITA 1.2 specification":
> 
> 
> 
> While the written specification and the DTDs and XSDs
> should be consistent, the written specification is normative if there is
> a discrepancy.  And, if there are discrepancies between different parts
> of the written specification, the Language references take precedence
> over the Architectural specifications.
> 
> 
> 
> My thinking for suggesting that the Language references
> take precedence is just that the Language reference tends to be more
> specific, while the Architectural specifications tend to be more
> general, and it seems better to have the specific trump the general when
> there are conflicts. But I'd be OK with having the Architectural
> specifications take precedence over the Language references if someone
> feels strongly about it.  The important thing is to pick an order of
> precedence and stick with it.
> 
> 
> 
> We might consider adding something like this at the end
> too:
> 
> 
> 
> If discrepancies are discovered, please notify the OASIS
> DITA Technical Committee so that the differences can be resolved in a
> future release.
> 
> 
> 
>   -Jeff
> 
> 
> 
> From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
> Sent: Tuesday, January 05, 2010 10:40 AM
> To: DITA TC
> Subject: Re: [dita] Normative language specification
> 
> 
> 
> From the DITA TC minutes for 15 December:
> 
> 3. ITEM - Status of language spec and Normative
> schema.
> 
> Response from M. McCrae is that the prose
> description takes precedence over the DTD. See -
> http://lists.oasis-open.org/archives/dita/200912/msg00035.html.
> 
> As I read Mary's post (below), we could and should
> specify whatever precedence we think is best.
> 
> * If the DTD (or schema, or both) code is
> "reproduced in the specification"--or, I suppose, if it is included by a
> performative text reference saying that it is "hereby included"--then
> "the plain text file" of code "takes precedence".
> * But "typically" the prose description in the
> spec should "be specified" to take precedence over the DTD. (Emphasis
> added.) 
> * "It's always helpful to call this out explicitly
> in the specification itself".
> * We should "specify which schema format (if any)
> is normative or takes precedence" (i.e. DTD vs. schema).
> 
> I don't see an OASIS dictum there, I see a range of
> choices and the recommendation that we make a decision, with some
> guidance as to what makes sense and what's typical.
> 
> 
> 
> Seth alluded to "some discussions recently that clearly
> indicate that DTD technology is insufficient to represent the normative
> language specifications", with the implication (or anyway my inference)
> that we consider making schema normative. He asked what was our position
> on this; SFAIK that question hasn't been clarified. (I can readily
> understand a view that the schema implementation should be constrained
> to what DTD can do, at least until tools more adequately and generally
> support schema.)
> 
>  
> 
> Jeff asked "is the order of priority:  DTDs, XSDs,
> Language Spec., Arch. Spec?"
> 
> 
> 
> (It is odd to have a reference document take normative
> precedence over a specification. If that is the case, maybe we should
> treat it as a specification that happens to be used as a reference.)
> 
> 
> 
> In summary, we should determine the normative order and
> specify it in the normative section of the spec. Has this been done?
> 
> 
> 
>    /Bruce
> 
> 
> 
> 
> ________________________________
> 
> 
> Subject: Re: [dita] Normative language specification
> 
> * From: Mary McRae <marypmcrae@gmail.com>
> * To: "Ogden, Jeff" <jogden@ptc.com>
> * Date: Tue, 1 Dec 2009 17:58:39 -0500
> 
> 
> ________________________________
> 
> Hi folks, 
> 
>  
> 
>  There seems to be much confusion around this rule. If the DTD is
> reproduced in the specification, the plain text file takes precedence.
> Unless your DTD or schema *is* your spec, the prose description would
> typically be specified to take precedence over the DTD. It's always
> helpful to call this out explicitly in the specification itself (that
> the prose takes precedence over any schema notation) but you'll also
> want to specify which schema format (if any) is normative or takes
> precedence.
> 
>  
> 
> Mary
> 
>  
> 
>  
> 
>  
> 
> On Dec 1, 2009, at 5:38 PM, Ogden, Jeff wrote:
> 
>  
> 
> Isn't having the DTDs be normative an OASIS rule?  If so, then our
> position may have been clarified for us already.
> 
>  
> 
> So is the order of priority:  DTDs, XSDs, Language Spec., Arch. Spec?
> All with the hope that we don't actually have any true conflicts.
> 
>  
> 
>     -Jeff
> 
>  
> 
> From: Park Seth-R01164 [mailto:R01164@freescale.com]
> Sent: Tuesday, December 01, 2009 1:08 PM
> To: dita
> Subject: [dita] Normative language specification
> 
>  
> 
> I've been spreading rumors that the DTDs are normative when there is a
> conflict between the lang spec and the DTDs.
> 
>  
> 
> There have been some discussions recently that clearly indicate that DTD
> technology is insufficient to represent the normative language
> specifications.
> 
>  
> 
> Can we clarify our position on this?
> 
>  
> 
> -sp
> 
>  
> 
> --------------------------------------------
> 
> seth park
> 
> information architect
> 
> Freescale Semiconductor, Inc.
> 
> seth.park@freescale.com
> 
> 512.895.2463
> 
>  
> 
> 
> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]