Fixes for OASIS DITA 1.0

The following changes include fixes for technical problems in the specification, as well as numerous corrections to comments in the DTD and XSD files. The suggested changes are grouped by type, with general changes first (including all technical problems), followed by incorrect element descriptions, typos, and entity issues.

Filename Change
catalog-dita.xml Lists a public ID pointing to topicAttr.ent. The file is actually named topicAttr.mod.
catalog-dita.txt lists 2 files as pointing to topicAttr.ent. The first should go to topicAttr.mod. The second should go to topicDefn.ent.
taskGrp.xsd The elements choption, chdesc, choptionhd, and chdeschd all have their group declaration stating that is a task element.
tblDeclMod.xsd For type entry.class, it specifies the default value for class attribute to be topic/tgroup. It should be topic/entry.
topic.mod, catalog-dita.txt, catalog-dita.xml The wrong public ID is used for tblDecl.mod. When DITA 1.0 was approved, the tables moved from the CALS model to the OASIS Exchange Table Model. The public ID was supposed to be updated to reflect this. The comment in tblDecl.mod indicates this decision, listing the public ID as:
-//OASIS//ELEMENTS DITA Exchange Table Model//EN
However, the catalogs and topic.mod still refer to this module using the old public ID:
-//OASIS//ELEMENTS DITA CALS Tables//EN
All references should use the Exchange Table Model ID.
mapMod.xsd, map.xsd The domains attribute is defined in map.class in the file mapMod.xsd. It should actually be defined in the file map.xsd using the redefine mechanism to include the domains attribute in the map.class content model. This fix allows users to specialize map and add a different domain.
map.dtd and map.mod Public ID is incorrect:
-//OASIS//Elements DITA Map//EN
should be
-//OASIS//ELEMENTS DITA Map//EN
catalog-dita.xml The <group> element around the DTDs should not use the xml:base attribute. The file is delivered in the same directory as the DTDs; it should be correct as delivered. Vendor implementations can update as appropriate.
topicAttr.mod @class and global-atts are declared twice for <title>
utilitiesDomain.ent, utilitiesDomain.mod Remove entity declaration for "ut-d-simpletable" in *.ent, remove header comment about message lists in *.mod (none of the other domains contains examples in the header - we should just remove the line)
All topic and map domain files, topicAttr.mod, topicDefn.ent, metaDecl.mod Update the "delivered as" system ID to match the real delivery name and extension
topic.mod Header lists the PURPOSE as defining items for the Programming Domain. Should say "Declaring the elements for the base Topic type."
softwareDomain.mod Header lists the PURPOSE as defining items for DITA XML Metadata. Should say "Declaring the elements and specialization attributes for the Software Domain."
utilitiesDomain.ent, uiDomain.ent, softwareDomain.ent, programmingDomain.ent, Most files include "All rights reserved" after the copyright, these do not. It should be added to these files.
ditabase.dtd, map.dtd, ditaarch.xsd, mapMod.xsd, mapGrp.xsd, map.xsd, ditabase.xsd Header says to see license.txt for disclaimers/permissions. This was the license when the files were distributed on developerWorks. The reference should be removed.
tblDeclGrp.xsd Does not contain any copyright statement (tblDecl.mod has the same copyright as other files). Will copy in the copyright from other XSD files.
ditabase.xsd, map.xsd, map.dtd Update version number in the header. These three use 1.3, all other files use 1.0. These three should also use 1.0.

Changes to LONG NAMEs

File name, element to change Change
highlightDomain.mod, all elements except <b> The descriptive name for every element is "Bold". The descriptive names should match the element: "Italic", "Underlined", etc.
topic.mod, <alt> element Currently says "Required Cleanup Block". Change to "Alternate text."
task.mod, <chdeschd> element Says "Choice Schedule". Change to "Choice Description Head"
reference.mod, <propdeschd> element Says "Property Schedule". Change too "Property Description Head"
uiDomain.mod, <screen> element Says "Screen Name", in fact it is a block element with the full screen display. Change to "Text Screen Capture"
programmingDomain.mod, <groupcomp> Says "Group Comparison", change to "Composite group". For the other groups, change "Group Sequence" to "Sequence Group" and "Group Choice" to "Choice Group".
topic.mod, <indextermref> Says "Link", change to "Index term reference"
programmingDomain.mod, <codeph> Says "Code Emphasis", change to "Code phrase"
programmingDomain.mod, <kwd> Says "Keyword", should the description be "Syntax keyword" to distinguish it from a <keyword>

Typos

File name Change
ALL DTD files change header comment "public identfier" to "public identifier"
mapgroup.mod, highlightDomain.mod, concept.mod PURPOSE comment refers to "specialization atttributed" rather than "specialization attributes" (extra t, d instead of s)
ditabase.dtd Fix 3 typos in PURPOSE comment
topic.mod, programmingDomain.mod Typo in purpose statement, "sepcialization"
topic.mod draft-comment LONG NAME uses "Bloc" instead of "Block"
reference.mod LONG NAME for <refsyn> uses "Refernce"

Entity updates

File name Change
map.mod, topic.mod defines %topicreftypes; which is never used. This is not a problem, but it defines "external" and "local" as type values. These were used long ago, and were replaced with @scope. The %topicreftypes; entity will be removed.
concept.mod, reference.mod, task.mod Remove these entity declarations, which are unused and point to nonexistent files:
<!ENTITY % conceptClasses SYSTEM "concept_class.ent"> 
<!ENTITY % referenceClasses SYSTEM "reference_class.ent"> 
<!ENTITY % taskClasses SYSTEM "task_class.ent">
topicDefn.ent Remove these entity declarations - the elements they correspond to were removed in DITA 1.0:
<!ENTITY % spanspec  "spanspec">
<!ENTITY % tfoot     "tfoot"   >

History

Most of these items were described in the previously posted "Suggested updates" document (http://www.oasis-open.org/committees/download.php/14757/suggestedUpdates.html). Items in that document that are not included here are:
  • There will not be any changes to the catalog for schemas.
  • The update to long description for "Property" will not be made.
The following items have been reported since the last update do that document, and are included in this list of fixes:
  • taskGrp.xsd must be updated. Several elements all declare that they are the "task" element.
  • tblDeclMod.xsd must be updated. The entry element is declared to be topic/tgroup - it must be topic/entry.
  • mapMod.xsd and map.xsd must be updated. The current definition prevents users from specialization a map and changing the included domains.

2005/11/15: One additional bug has been found in the DTDs. The table module tblDecl.mod is referenced several times using the old CALS ID. When the files were approved by OASIS, the expectation was that this module would be referenced using a new public ID. This intention is clear within the table module itself, but was not carried through to the referencing files. Both catalog files and topic.mod should be updated to use the correct public ID.