Considerations for generalizing foreign elements

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition
Version
1.3
Author
OASIS DITA Technical Committee

The foreign element can contain a mixture of DITA and non-DITA content. Non-DITA content that is contained within a foreign element cannot be generalized. However, the foreign element itself, as well as any DITA elements that it contains, can be generalized using normal rules.

If a foreign element contains non-DITA content, the non-DITA content can be exported to a separate file and replaced in-line with an object element. The data attribute of the object element would reference the generated file, and the type attribute of the object element would be set to the value "DITA-foreign".

If an object element is present within the foreign element during generalization, it is not included with the content that is exported to the separate file. This original objectelement is used to specify alternate content in publishing systems that cannot display the foreign content. It would not be modified except as the ordinary rules of generalization require it.

In the exported file, exported content would be enclosed within a root foreign element in order to accommodate the possibility that it might contain several main elements apart from the alternate content.

For easy recognition, the name of the exported file would start with "dita-generalized-" , and it is recommended that the file name also contain the topic ID, specialization type, and element ID or generated identifier.

Example: Simple object generalization

For example, a DITA document could contain a specialization of foreign for MathML using the MathML domain that ships with DITA 1.3. It could look like this:

<mathml class="+ topic/foreign mathml-d/mathml ">
  <m:math>
    <m:mi>x</m:mi><m:mo>+</m:mo><m:mn>3</m:mn>
  </m:math>
  <data-about>X plus three</data-about>
</mathml>

The mathml container is a DITA element, so it should be generalized using normal rules. The m:math element, which is not a DITA element, will be exported to another file. The data-about element will remain:

<foreign class="+ topic/foreign mathml-d/mathml ">
  <object data="dita-generalized-topicid_mathml1.xml" type="DITA-foreign"/>
  <data-about>X plus three</data-about>
</foreign>

Contents of dita-generalized-topicid_mathml1.xml:
<foreign class="+ topic/foreign mathml-d/mathml "
         xmlns:m="http://www.w3.org/1998/Math/MathML">
>
  <m:math>
    <m:mi>x</m:mi><m:mo>+</m:mo><m:mn>3</m:mn>
  </m:math>
</foreign>

Example: Multiple object generalization

An object might also contain multiple object elements:

<mathml class="+ topic/foreign mathml-d/mathml ">
  <m:math>
    <m:mi>x</m:mi><m:mo>+</m:mo><m:mn>3</m:mn>
  </m:math>
  <data-about>X plus three</data-about>
  <m:math>
    <m:mi>y</m:mi><m:mo>-</m:mo><m:mn>2</m:mn>
  </m:math>
</mathml>

The mathml container, which is a normal DITA element, should be generalized using normal rules. A file should generated for each set of elements bounded by the container and any existing object elements. In this case, two files will be generated, and two new object elements added to the source.

The modified source:

<foreign class="+ topic/foreign mathml-d/mathml ">
  <object data="dita-generalized-topicid_mathml1.xml" type="DITA-foreign"/>
  <data-about>X plus three</data-about>
  <object data="dita-generalized-topicid_mathml2.xml" type="DITA-foreign"/>
</foreign>

The contents of dita-generalized-topicid_mathml1.xml, the first exported file:

<foreign class="+ topic/foreign mathml-d/mathml "
         xmlns:m="http://www.w3.org/1998/Math/MathML">
  <m:math>
    <m:mi>x</m:mi><m:mo>+</m:mo><m:mn>3</m:mn>
  </m:math>
</foreign>

The contents of dita-generalized-topicid_mathml2.xml, the second exported file:

<foreign class="+ topic/foreign mathml-d/mathml "
         xmlns:m="http://www.w3.org/1998/Math/MathML">
  <m:math>
    <m:mi>y</m:mi><m:mo>-</m:mo><m:mn>2</m:mn>
  </m:math>
</foreign>