Suggested Updates to DITA 1.0 Specification

The suggested changes correct a couple of technical problems in the specification, as well as suggesting numerous corrections to comments in the DTD and XSD files. The suggested changes are grouped roughly 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.
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.
catalog-dita.xml The catalog should be updated to include schemas.
map.dtd and map.mod Public ID is incorrect:
-//OASIS//Elements DITA Map//EN
should be
-//OASIS//ELEMENTS DITA Map//EN
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, or remove the "delivered as" line from all DTD files.
topic.mod Header lists the PURPOSE as defining items for the Programming Domain. Should say "Declaring the elements and specialization attributes 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
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)
ditabase.xsd, map.xsd, map.dtd Update version number in the header. They use 1.3, all other files use 1.0.

Changes to LONG NAMEs

File name, element to change Change
highlightDomain.mod, all elements except <b> The name for every element is "Bold"
topic.mod, <alt> Currently says "Required Cleanup Block"
task.mod, <chdeschd> Says Choice Schedule, should be Choice Description Head
reference.mod, <propdeschd> Says "Property Schedule", should be "Property Description Head"
uiDomain.mod, <screen> Says Screen Name, in fact it is a block element with the full screen display
programmingDomain.mod, <groupcomp> Says "Group Comparison", should be "Group Composite"

Side-note: for the 3 group types, would it read easier to say "NNN group" instead of "Group NNN". The element names were chosen to ensure they group together in an element list.
topic.mod, <indextermref> Says "Link", should say "Index term reference"
programmingDomain.mod, <codeph> Says "Code Emphasis" - should be "Code phrase"
reference.mod, <property>
Note: This change will not be implemented, because the DTD does not comment upon the final appearance for any properties elements.
Says "Property" - should be Property Row, to clarify that it is a row in the table
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.
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"   >

Change history