Considerations for generalizing <foreign> elements

(Non-normative) Generalization of a DITA element employs the value of its @class attribute. The content of a <foreign> element, or of a specialization of the <foreign> element, cannot be generalized because there are no DITA elements in it, and therefore no @class attributes. The non-DITA contents can only be processed by appropriate non-DITA means.

Only the specialization of the <foreign> element can be generalized with normal rules.

Its contents would be exported to a separate file and replaced in-line with an <object> element. The data attribute of the <object> element would point to 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 (or specialization thereof) during generalization, it would not be 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 may 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. 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>
</mathml>

The <mathml> container is a DITA element, so it 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>
</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/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>

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

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

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

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