Specializing foreign or unknown content

Specializing the <foreign> or <unknown> element is an open extension to DITA for the purpose of incorporating standard vocabularies for non-textual content, such as MathML and SVG, as in-line objects. These elements should not be used to include textual content or metadata in DITA documents except where such content acts as an example or display, rather than as the primary content of a topic.

Incorporating foreign or unknown content

There are three methods of incorporating foreign content into DITA.

A domain specialization of the <foreign> or <unknown> element. This is the usual implementation.
A structural specialization using the <foreign> or <unknown> element. This affords more control over the content.
Do nothing: simply embed the foreign content within <foreign> or <unknown>.

Foreign or unknown content and the architectural @class attribute

Foreign content that is incorporated in DITA by one of these methods is not specialized. Specialization depends upon the architectural @class attribute found in every DITA element. If the foreign content has interoperability or vocabulary naming issues such as those that are addressed by specialization in DITA, they must be addressed by means that are appropriate to the foreign content.

Example of specializing foreign or unknown content using DTDs

The sample below describes how to create a domain declaration of the svg element, but does not show how to integrate that declaration in a DITA document-type shell. For more specific information on creating document-type shells, see DTD syntax specialization module coding requirements.

<!-- declaration for the specialized wrapper -->
<!ENTITY % svg "svg">

<!-- included SVG document type -->
<!ENTITY % SVG.prefix "svg" >
<!ENTITY % svg-qname.mod
    PUBLIC "-//W3C//ENTITIES SVG 1.1 Qualified Name//EN"
           "svg-qname.mod" 
>%svg-qname.mod;

<!-- definition for the specialized wrapper  -->
<!ENTITY % svg.content "
     (%SVG.svg.qname;)
">
<!ATTLIST % svg.attributes "
">
<!ELEMENT svg %svg.content; >
<!ATTLIST svg %svg.attributes; >

<!ATTLIST svg %global-atts; class CDATA "+ topic/foreign svg-d/svg ">

Note: The example assumes that parameter entity SVG.svg.qname is declared in the SVG DTD or schema.

Example of SVG within a <p> element

<p>This is an ellipse:
  <svg>
    <svg:svg width="100%" height="100%" version="1.1"
xmlns="http://www.w3.org/2000/svg">

<ellipse cx="300" cy="150" rx="200" ry="80"
style="fill:rgb(200,100,50);
stroke:rgb(0,0,100);stroke-width:2"/>

    </svg:svg>    
  </svg>.
</p>

Example of specializing foreign content using XML Schemas

The sample below describes how to create a domain declaration of the mathML element, but does not show how to integrate that declaration in a DITA document-type shell. For more specific information on creating document-type shells, see XSD schema specialization module coding requirements

<!-- importing MathML document type --> 
<xs:import namespace="http://www.w3.org/1998/Math/MathML" schemaLocation="mathml2.xsd">
 
<!-- definition for the specialized wrapper  -->
<xs:element name="mathML" type="mathML.class" />
<xs:complexType name="mathML.class">
  <xs:choice>
      <xs:element ref="mml:math" />
  </xs:choice>
  <xs:attribute name="outputclass" type="xs:string"/>
    <xs:attributeGroup ref="univ-atts"/>
    <xs:attributeGroup ref="global-atts"/>
    <xs:attribute ref="class" default="+ topic/foreign mathML/mathML"/>
</xs:complexType>

<!-- definition for each element extended by the domain  -->    
<xs:group name="ma-d-foreign">
  <xs:choice>
     <xs:element ref="mathML" />
  </xs:choice>
</xs:group>
  
<!-- definition for the named model groups  -->
<xs:group name="foreign">
   <xs:choice>
     <xs:group ref="foreign"/>
     <xs:group ref="ma-d-foreign"/>
   </xs:choice>
</xs:group>

Example of MathML within an <object> element

<p>... as in the formula 
<object>
  <desc>4 + x</desc>
  <mathML>
    <mml:math display="block">
      <mml:mrow>
        <mml:mo>&sum;</mml:mo>
        <mml:mn>4</mml:mn>
        <mml:mo>+</mml:mo>
        <mml:mi>x</mml:mi>
      </mml:mrow>
    </mml:math>    
  </mathML>
 <object>.
</p>