Small Problems with the DITA Standard

Over the years, many of our Oxygen XML Editor clients (or me, personally) have encountered various limitations/quirks in the DITA standard and I will share them below. These complaints are not related at all to the publishing part and I think that some of them will probably be resolved as the DITA standard evolves from one version to another. Also, many of these issues could not be effectively fixed since the DITA standard has strived (and succeeded) to be backward compatible and thus, the issues remain from version to version. So here we go:

• When I create a DITA specialization, to add a new attribute according to the specification I need to add that attribute to all DITA elements. I think the main idea was that the new attribute is a profiling attribute so it makes sense to be added to all elements, but sometimes you need to funnel this behavior and make the attribute available only on a certain element and still consider the specialization as a valid DITA specialization.
• The existing xml:lang attribute cannot be used to profile and filter out content. In the past, we had users somehow mixing languages in the same DITA Map and expecting to create output for one language or the other by filtering based on the xml:lang attribute.
• You cannot easily profile/filter out an entire column from a CALS table. For example, you cannot add a profiling attribute directly to the DITA colspec element to remove entire table columns when publishing. So the alternative is to use a DITA simple table and define the profiling attribute on each of the cells in the column or to perform some kind of output customization based on a magic outputclass attribute set on a certain element in the table.
• There are too many constraints imposed when writing DITA specializations. Robert Anderson, the DITA OT project manager and OASIS member involved in defining the DITA standard, had two interesting blog posts on this:
  • http://metadita.org/toolkit/ditasplainer.html
  • http://metadita.org/toolkit/nonononodomains.html
• With most of the material being published for web and with the need to dynamically include media resources (video, audio) in the published HTML content, it's a pity that the DITA standard does not yet have specialized <audio> and <video> elements. Again, we need to rely on the magic outputclass attribute to give semantic to the generic DITA <object> element.
• Sometimes there are two or more ways of doing something. For example, choosing between using a CALS table or a simple table or choosing between using conkeyref, keyref, or conref to reuse small pieces of text. Why even have the <simpletable> element in the DITA standard at all, since a CALS table without cells spanning is simple enough? The LightWeight DITA Project is an alternative to DITA and it tries to simplify the standard and eliminate such problems: http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.html.
• DITA elements that have conrefs or conkeyrefs need to also have the required content specified in them. So I cannot simply do this:

  <table conref="path/to/target.dita#topicID/elementID"/>

  Instead, I need to do this:

  <table conref="path/to/target.dita#topicID/elementID">
    <tgroup cols="1">
     <tbody>
       <row>
         <entry/>
       </row>
    </tbody>
   </tgroup>
  </table>

  and have all the required table elements and tgroup elements (plus required attributes) filled out even if the expanded conref will replace the entire original element.
• You cannot reference directly to a subtopic element using a key. If the standard would allow a DITA Map to reference directly to a subtopic element like this:

  <keydef href="topics/reusableComponents.dita#topicID/tableID" keys="reused_table"/>

  you could reuse the table without needing to specify the ID to the reused element on each conkeyref:

  <table conkeyref="reused_table"/>

• Some DITA elements (eg: <li>, <entry>, <section>) have a very relaxed content model in the specification allowing both text and block elements, in any order. So when using visual editing tools, this leads technical writers to create DITA content that looks like this:

      <li>
          Preview:
          <p>Here are some of the preview</p>
      </li>

  as the visual editing tool cannot, by default, impose an editing constraint if the standard does not. Usually, for such cases additional Schematron checks can be handy.
• The DITA content is not automatically profiled based on the new DITA 1.3 deliveryTarget attribute. So setting deliveryTarget="pdf" on a DITA element will not automatically filter it out of the HTML based outputs, the attribute is treated just like another profiling attribute, and it can be filtered out from the DITAVAL file.