From: firstname.lastname@example.org [mailto:email@example.com] On Behalf Of Kristen James Eberlein
Sent: June-04-12 3:27 PM
To: DITA TC
Subject: [dita] Fwd: [dita-comment] DITA 1.2 spec: clarification of @scale description defined in display-atts entity
Forwarding an e-mail from the <dita-comment> list. We'll add this to tomorrow's agenda.
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
+1 919 682-2290; kriseberlein (skype)
-------- Original Message --------
The description for @scale in the DITA 1.2 spec is somewhat misleading to me and some of my company's clients:
I suggest a clarification be considered for the documentation for the @scale attribute.
The "Description" for @scale reads (in part):
"Specifies a percentage, selected from an enumerated list[...]"
The term "enumerated list" has specific meaning in the context of a DTD. It might also be confused with the term "enumeration" in the context of a W3C Schema. People may use the term "enumerated list" for both DTD and XSD as they are effectively the same thing.
In addition, the definition for "Data Type" strongly resembles an enumerated list in a DTD attribute definition, which may also be misleading:
(50 | 60 | 70 | 80 | 90 | 100 | 110 | 120 | 140 | 160 | 180 | 200 | -dita-use-conref-target)
If these values are to be the only values allowed (the description does not make this clear) then there are quite a few tools on the market that are in violation of the spec because they are reading the DTD and allowing all valid CDATA values without restriction (this includes the DITA Open Toolkit, my own company's product XMetaL Author Enterprise, and most other tools that use a standard XML parser for validation). I suspect they are really meant only as suggestions since they appear to be fairly arbitrary. Why not go lower than 50% or higher than 200%? Why jump mostly by tens but skip a few?
I would recommend one of the following:
1. Leave the DTD untouched and alter the language used to describe this attribute. Make it clear that the list of values shown is either recommended or merely an example. I would specifically recommend avoiding the use of the term "enumerated list" here as I believe it is misleading.
2. Alter the DTD to define this attribute as an enumerated list that allows the values described for "Data Type".
I suspect clarification of the "Description" and "Data Type" might be the least disruptive option.
Program Manager, XMetaL
JustSystems Canada, Inc.