Considerations for generalizing <foreign> elements

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 <object>element 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>