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


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.

512.895.2463

 

 



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