dita — archive
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:[email protected]]
Sent: Wednesday, January 13, 2010 2:50 PM
To: Bruce Nevin (bnevin); DITA TC
Subject: RE: [dita] Normative language specificationBruce,
Are you suggesting that we have a different precedence for DITA 1.2 or just making an observation?
-Jeff
From: Bruce Nevin (bnevin) [mailto:[email protected]]
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:[email protected]]
Sent: Tuesday, January 12, 2010 3:17 PM
To: DITA TC
Subject: RE: [dita] Normative language specificationBack 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:[email protected]]
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 <[email protected]>
- To: "Ogden, Jeff" <[email protected]>
- 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:[email protected]]
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