Foreign generalization

During generalization, DITA elements are modified based on the class attribute to use the name of an ancestor element. This cannot be done with the contents of a specialized <foreign> element, because the contents are not DITA elements and do not have class attributes.

Instead, only the specialized foreign element itself should be generalized with normal rules. The contents of the foreign element should be exported to a separate file, and replaced in-line with an <object> element. The object element should point to the generated file using its data attribute. The type attribute on the object element should be set to "DITA-foreign".

The object element is already allowed within the <foreign> element. If it is present during generalization, it should not be exported to the separate file. The original object element should not be modified unless required by the ordinary rules of generalization. That object element is used for alternate content in publishing systems that cannot display the foreign content.

A foreign content element may contain several main elements, apart from the alternate content. To accommodate this, the exported content should have a root <foreign> element.

The name of the exported file should start with "dita-generalized-" in order to help users recognize the origin of the generated files. It is recommended that the file name also contain the topic ID, specialization type, and element ID or generated identifier. For example, the first mathml object in topic "topicid" might be named "dita-generalized-topicid-mathml1.xml".

Example: Simple object generalization

For example, a DITA document may contain a specialization of <foreign> for MathML. It could look like this:

<mathml class="+ topic/foreign mathml/mathml ">
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mi>x</mi><mo>+</mo><mn>3</mn>
  </math>
  <object><desc>X plus three</desc></object>
<mathcontent>

The mathml container, which is a normal DITA element, should be generalized using normal rules. The <math> element, which is not a DITA element, will be exported to another file. The <object> element will remain:

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

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

Example: Multiple object generalization

An object might also contain multiple object elements:

<mathml class="+ topic/foreign mathml/mathml ">
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mi>x</mi><mo>+</mo><mn>3</mn>
  </math>
  <object><desc>X plus three</desc></object>
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mi>y</mi><mo>-</mo><mn>2</mn>
  </math>
<mathcontent>

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:

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

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

Contents of dita-generalized-topicid_mathml2.xml:
<foreign class="+ topic/foreign mathml/mathml ">
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mi>y</mi><mo>-</mo><mn>2</mn>
  </math>
</foreign>