Considerations for generalizing <foreign> elements
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>