<foreign>

Foreign content is non-DITA content, such as MathML, SVG, or Rich Text Format (RTF).

Usage information

Specializations of the <foreign> element are typically implemented as domains, but it is also possible to implement foreign vocabularies as structural specializations.

The <foreign> element can contain non-DITA content or a mix of DITA and non-DITA content.

If alternate content is wanted, use or specialize the <desc> element inside of the <foreign> specialization. Such alternate content needs to be valid wherever the <foreign> specialization is valid. This way, if a processor is not able to recognize or render the <foreign> content itself, it can use the alternate content from <desc>. Alternate content can also be provided using <image> or <object>.

Processing expectations

Processors attempt to display <foreign> content unless otherwise instructed. If a processor cannot render the content, it MAY issue a warning.

Draft comment: Kristen J Eberlein 28 December 2021
The following content needs editing.
Draft comment: robander
TO RESOLVE 13 May 2026: We or the magic robots should do a single editing pass and call it done

Also noted … the first rule, about <desc>, the 1.3 language (still present) says to treat like <section>, but with no title. I don't know anymore what that means, and desc is not allowed in section (my first read is "treat desc in foreign like you would treat desc in section" but that can't be right)

Suggested rework of the following paragraph and list:

By the nature of the element, content within a <foreign> element is unexpected in a DITA context. For this reason, the enabler of a foreign vocabulary typically needs to extend tools or provide processing support for the new content.

  • If <foreign> contains more than one element to provide alternative content, each should be processed.
  • When alternative content is provided using <desc>, processors will typlically render each <desc> similar to a <div> in HTML, but this is not required.
  • If no <desc>, <object>, or <image> element is found within an instance of the <foreign> element, a processor can emit a warning about the absence of processable content.
  • The base processing for <object> might emit the content of <foreign> as a file at the location specified by the @data attribute of the <object> element, turning the inline foreign content into a referenced object to be handled by rendering tools.
  • When used to provide alternative content inside of <foreign>, the <object> element should have a data attribute or a <foreign> sub-element but not both. If both are present, a processor can choose which to ignore.

The enabler of the foreign vocabulary must provide the processing and override the base processing for <foreign>.

  • If <foreign> contains more than one alternative content element, they should all be processed. In the case of <desc> they should be concatenated in a similar way to <section>, but with no title (analogous to <div> in HTML).
  • If no <desc>, <object>, or <image> element is found within an instance of the <foreign> element, the base processing can emit a warning about the absence of processable content.
  • The base processing for <object> might emit the content of <foreign> as a file at the location specified by the @data attribute of the <object> element. The <object> element should have a data attribute or a <foreign> sub-element but not both. In the event that an <object> element contains both a data attribute and an <foreign> sub-element the processing system should ignore one of them.

Content model

Any

Contained by

<abstract>, <alt>, <audio>, <author>, <b>, <body>, <bodydiv>, <brand>, <category>, <cite>, <component>, <consequence>, <coords>, <copyrholder>, <data>, <dd>, <ddhd>, <desc>, <div>, <draft-comment>, <dt>, <dthd>, <em>, <entry>, <example>, <fallback>, <featnum>, <fig>, <figgroup>, <fn>, <i>, <include>, <index-see>, <index-see-also>, <indexterm>, <li>, <line-through>, <lines>, <linkinfo>, <linktext>, <linktitle>, <lq>, <metadata>, <navtitle>, <note>, <object>, <overline>, <p>, <ph>, <platform>, <pre>, <prodname>, <prognum>, <prolog>, <publisher>, <q>, <searchtitle>, <section>, <series>, <shortdesc>, <sli>, <source>, <stentry>, <strong>, <sub>, <subtitle>, <sup>, <title>, <titlealt>, <titlehint>, <tt>, <typeofhazard>, <u>, <video>, <xref>

Any content

Contained by

Inheritance

- topic/foreign

The <foreign> element is a base element type. It is defined in the topic module.

Attributes

The following attributes are available on this element: universal attributes.

The following attributes are available on this element: universal attributes.

Example

This section is non-normative.

The following code sample shows a specialization of <foreign> that is used to hold SVG elements. For this to work, the specialization module that defines <svg-container> also needs to include the definitions for the SVG elements.

<p>To turn on your product, press the elliptical orange button:
  <svg-container>
    <svg:svg width="100%" height="100%" version="1.1">
      <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-container>.</p>