• New design patterns for 1.1

New DTD and Schema patterns for DITA 1.1

ISSUE: With DITA 1.1 there are many elements that will be used in both map and topic. This comes about primarily because of the new <data> element, which can be used in both maps and topics; data allows ph, image, and object, which in turn bring in most content elements outside of links, section, and example.

Currently, shared meta elements are defined in metaDecl.mod. The only other shared elements are keyword and shortdesc, which are declared independently. With so many elements now in common, the shared elements should be stored a common location. metaDecl.mod does not make sense because these are not meta elements, so a new module is needed.

PROPOSAL: Create a new module named commonElements.mod. This will include non-meta elements that are shared between topics and maps.

NOTES:

• The commonElements.mod file will need to include virtually every content element that is allowed in the topic body (full list below). This is because data allows object, which allows desc, which allows all blocks and phrases other than sections and examples.
• The only way to include most of these elements in a map is to nest phrases or objects within the data element, which processing will ignore by default (it is only useful when specialized). Specializations may tighten this model to disallow many or all of the topic elements.
• Declaring the elements in a common location will allow a single domain specialization to be used in both maps and topics. For it to be reusable, a domain must define only elements based on the common content or meta elements.

  • Note: This means that some, but not all, of the current OASIS domains could theoretically be added to maps. The highlighting, software, and ui domains could be included, because they use only common elements. The programming and utilities domains could not, because they each include a specialization of <fig>.

• Class attributes for the common elements will continue to begin with "- topic/... " as they do for meta elements.

  • Note: The shortdesc element in maps today is defined with class="- map/shortdesc ". This means creating a common definition would be a backwards incompatible change for processors. However, we can make the content models match until 2.0 when the elements are consolidated.

• The DTD changes are described below. Eric Sirois needs to be consulted on related Schema changes.

DTD changes

Current DTD setup

• map.mod declares all elements used exclusively in the map; it also declares keyword (stricter content model than in topic, but uses topic's class attribute), and declares shortdesc (different content model and class attribute). The file includes the entity definition, element content model, and class attributes for each element.
• topic.mod declares all elements used exclusively in topics. Contains its own definition of keyword and shortdesc.
• topicAttr.mod declares the class attribute for all elements used exclusively in topics.
• topicDefn.ent declares the entity for every element used in topic (including meta elements)
• metaDecl.mod declares meta elements that are used in both topic and map. It contains the entity definitions, element and content model, and class attributes for each element. Note that the entity definitions are declared twice (here and topicDefn.ent)
• tblDecl.mod declares the CALS/OASIS Exchange table elements. It contains the entity definitions, element and content model, and class attributes for each element. Note that the entity definitions are declared twice (here and topicDefn.ent)

New files for 1.1

• commonElements.mod will declare all elements that are now used in both topic and in map. It will include the class attributes as well. Current prototyping indicates that the following elements must be declared in this file (does not include most new 1.1 elements):
  • data, data-subject;
  • title, desc, p, note, lq, pre, lines, object, param;
  • sl, sli, ul, ol, li, itemgroup;
  • dl, dlhead, dthd, ddhd, dlentry, dt, dd;
  • q, keyword, term, ph, tm, boolean, state, image, alt, fn, cite, xref, indextermref;
  • simpletable, sthead, strow, stentry;
  • table, tgroup, thead, tbody, colspec, row, entry
  • fig, figgroup;
  • draft-comment, required-cleanup;
  • indexterm (moved from metaDecl.mod)
• commonElements.ent will define the entity for all of the common elements (including meta elements). It will be imported into topicDefn.ent, so that users importing topicDefn.ent will continue to get all topic elements. It will also be pulled into commonElements.mod.

For completeness, here is a list of "topic-only" elements from DITA 1.0 that remain in topic.mod: topic, titlealts, navtitle, searchtitle, shortdesc (to be moved in 2.0), body, no-topic-nesting, section, example, prolog, metadata, related-links, link, linktext, linklist, linkinfo, linkpool.

Changes to existing DTD files

• Move the definition of keyword from both topic and map into commonElements.mod
• Move the listed elements from topic.mod into commonElements.mod
• Move the indexterm element from metaDecl.mod into commonElements.mod
• Reference tblDecl.mod from inside commonElements.mod. The table elements are common, so even though they are in another module, they should be pulled in by commonElements.mod.
• Update the content model of shortdesc in map to match the content model in topics, so that they are equivalent to users, if not to processors.
• Update map.mod and topic.mod to reference commonElements.mod, as they do today for metaDecl.mod.
• Remove the reference to tblDecl.mod from topic.mod, because it is part of commonElements.mod.
• topicAttr.mod will be removed. Class attributes for common elements will be moved to commonElements.mod. Class attributes for topic-only elements will be moved to topic.mod.
• topicDefn.ent will declare entities for topic-only elements. It will import commonElements.ent, which defines entities for all common elements.