Part I, Chapter 8. Rich media content

§ SVG

It is possible to include SVG graphics in a DITA document either by reference or by inclusion. Use an <svg-container>/<svgref> element pointing to an SVG file to include it by reference. Example:

The XML source code corresponding to the above example is:

<p><svg-container><svgref href="media/graphic.svg"/></svg-container></p>

It's also possible to use an <image> element pointing to an SVG file to include it by reference. Example:

<p><image href="media/graphic.svg"/></p>

Embedding SVG graphics in a DITA document can be achieved using the same <svg-container> element. Example:

The XML source code corresponding to the above example is:

<p><svg-container>
  <svg:svg height="64.710144" version="1.1"
    viewBox="0 0 104.28986 51.768115" width="130.36232"
    xmlns:svg="http://www.w3.org/2000/svg">
  ...
  </svg:svg>
</svg-container></p>

Embedding SVG

It is still recommended to include SVG graphics by reference using the <image> element rather then <svg-container>/<svgref>. The <image> element has useful attributes (@width, @height, @scale, @scalefit) allowing to adjust the dimension of the image. Moreover this elements permits on the fly conversion between image formats.
It is not recommended to embed SVG elements in a DITA document as this is likely to cause many validation problems.
An embedded SVG element is kept embedded only when generating the following output formats: XHTML 5, XHTML 5 Web Help, EPUB 3 and all XSL-FO based output formats (PDF, RTF, DOCX, etc). For any other output format, an embedded SVG element is automatically extracted and replaced by an <image> element pointing to a ".svg" file.

§ MathML

It is possible to include math in a DITA document either by reference or by inclusion. Use an <mathml>/<mathmlref> element pointing to a MathML file to include it by reference. Example:

$math.svg$

The XML source code corresponding to the above example is:

<p><mathml><mathmlref href="media/math.mml"/></mathml></p>

Embedding MathML in a DITA document can be achieved using the same <mathml> element. Example:

The XML source code corresponding to the above example is:

<p><mathml>
  <m:math display="block" 
    xmlns:m="http://www.w3.org/1998/Math/MathML">
    <m:row>
    ...
    </m:mrow>
  </m:math>
</mathml></p>

For clarity, it is recommended to wrap <mathml> into the following equation elements: <equation-inline>, <equation-block>, <equation-figure>. Example:

Equation 8-1. Gauss's law in its differential form

The XML source code corresponding to the above example is:

<equation-figure>
  <title>Gauss's law in its differential form</title>
  <mathml>
    <m:math display="block"
      xmlns:m="http://www.w3.org/1998/Math/MathML">
      <m:mrow>
      ...
      </m:mrow>
    </m:math>
  </mathml>
</equation-figure>

Other example, <equation-block> elements containing a empty <equation-number> (to be automatically filled with an equation number):

(8-1)

Note that the counter used to number to <equation-figure> elements having a <title> and the counter used to number <equation-block> elements containing an empty <equation-number> are different. Therefore mixing numbered <equation-figure>s and numbered <equation-block>s in the same DITA document may result in a hard to understand equation numbering.

Embedding MathML

An embedded MathML element is kept embedded only when generating the following output formats: XHTML 5, XHTML 5 Web Help, EPUB 3 and all XSL-FO based output formats (PDF, RTF, DOCX, etc), but only when Apache FOP or XMLmind XSL-FO Converter are used as an XSL-FO processor⁽¹⁾. For any other output format, an embedded MathML element is automatically extracted and replaced by an <image> element pointing to a ".mml" file.
Though a number of web browsers natively support embedded MathML, it's recommended to specify XSLT stylesheet parameter mathjax to let MathJax render embedded MathML found in the generated XHTML 5 and XHTML 5 Web Help files.
A ".mml" file is automatically converted to SVG or PNG by the means of the JEuclid image converter. Such image converter is found the ditac-N_N_N-plus-fop.zip distribution and is automatically registered with ditac.

§ TeX/LaTeX math

Embedding TeX/LaTeX math in a DITA document can be achieved by inserting a <foreign> element having an @outputclass attribute containing "embed-latex"⁽²⁾ preferably into an <equation-inline>, <equation-block> or <equation-figure> element. Example:

(8-2)

The XML source code corresponding to the above example is:

<equation-block><foreign outputclass="embed-latex"
  >$$\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$$</foreign>
  <equation-number/>
</equation-block>

Tip

TeX/LaTeX math delimiters are optional. However specifying them may be useful as \[math\], $$math$$ or \begin{env_name}math\end{env_name} specify displayed math, while $math$ or $math$ specify in-line math.

It's also possible to insert an <image> element pointing to an ".tex" file into an <equation-inline>, <equation-block> or <equation-figure> element. Example:

.

The XML source code corresponding to the above example is:

<p>... Example:
<equation-inline><image href="media/limits.tex"/></equation-inline>.</p>

Embedding TeX math

EmbeddedTeX/LaTeX math is kept embedded only when generating the following output formats: XHTML 5 and XHTML 5 Web Help. For any other output format, EmbeddedTeX/LaTeX math is automatically extracted and replaced by an <image> element pointing to a ".tex" file.
XSLT stylesheet parameter mathjax must be specified to let MathJax render embeddedTeX/LaTeX math found in the generated XHTML 5 and XHTML 5 Web Help files.
A ".tex" file is automatically converted to SVG or PNG by the means of the JLaTeXMath image converter. Such image converter is found the ditac-N_N_N-plus-fop.zip distribution and is automatically registered with ditac.
JLaTeXMath is currently less capable than MathJax , yet all the following TeX/LaTeX commands are available:
- macros from amsmath and symbols from amssymb and stmaryrd
- TeX macro \over
- accents from amsxtra package
- macros \definecolor, \textcolor, \colorbox and \fcolorbox from the package color
- macros \rotatebox, \reflectbox and \scalebox from the package graphicx
- most latin, cyrillic and greek characters are available
- commands \newcommand and \newenvironment
- environments array, matrix, pmatrix,..., eqnarray, cases
- vertical and horizontal lines are handled in array environment
- commands to change the size of the font are available : \tiny, \small,..., \LARGE, \huge, \Huge

§ Audio

Use the <object> DITA element to add audio to your DITA topics. Example:

audio.mp3 (audio/mpeg)

The XML source code corresponding to the above example is:

<p><object data="media/audio.mp3" type="audio/mpeg">
     <param name="source" value="media/audio.ogg"
            valuetype="ref" type="audio/ogg"/>

     <param name="source" value="media/audio.m4a"
            valuetype="ref" type="audio/mp4"/>

     <param name="source" value="media/audio.wav"
            valuetype="ref" type="audio/wav"/>

     <param name="controls" value="true"/>
</object></p>

Notes:

The @data and @type attributes are required. The value of the @type attribute must start with "audio/".
It is strongly recommended to specify alternate audio files as modern web browsers, while all supporting the HTML 5 <audio> element, vary in their support of audio formats. This is done by adding <param> child elements to the <object> element. Such <param> elements must have a name="source" attribute, a valuetype="ref" attribute, a @value attribute referencing an audio file and preferably, a @type attribute specifying the media type of the audio file.
It is possible to add <param> elements corresponding to the attributes supported by the HTML 5 audio element (<crossorigin>, <preload>, <autoplay>, <mediagroup>, <loop>, <muted>, <controls>). In the above example, we have added a <param> element corresponding to the @controls HTML 5 attribute. Note that in the case of HTML 5 boolean attributes (<autoplay>, <loop>, <muted>, <controls>), the @value attribute of a <param> is not significant. For example, in the case of the above example, you could have specified "yes", "on", "1", etc, instead of "true".
If the <object> element has a <desc> child element, then this <desc> element is used to generate fallback content in case audio is not supported. If the object element has no <desc> child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the audio file.
When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the output file.

Lightweight DITA

has an <audio> element, so there is no need to use an <object> element. The equivalent of the above <object> example would be:

<audio>
  <media-controls value="true"/>

  <media-source value="media/audio.mp3"/>
  <media-source value="media/audio.ogg"/>
  <media-source value="media/audio.m4a"/>
  <media-source value="media/audio.wav"/>
</audio>

§ Video

Use the <object> DITA element to add video to your DITA topics. Example:

video.mp4 (video/mp4)

The XML source code corresponding to the above example is:

<p><object data="media/video.mp4" type="video/mp4">
     <param name="source" value="media/video.ogv"
            valuetype="ref" type='video/ogg; codecs="theora, vorbis"'/>

     <param name="source" value="media/video.webm"
            valuetype="ref" type="video/webm"/>

     <param name="width" value="320"/>
     <param name="controls" value="yes"/>
     <param name="poster" value="media/video_poster.jpg"
            valuetype="ref"/>
</object></p>

Notes:

The @data and @type attributes are required. The value of the @type attribute must start with "video/".
It is strongly recommended to specify alternate video files as modern web browsers, while all supporting the HTML 5 <video> element, vary in their support of video formats. This is done by adding <param> child elements to the <object> element. Such <param> elements must have a name="source" attribute, a valuetype="ref" attribute, a @value attribute referencing a video file and preferably, a @type attribute specifying the media type of the video file.
It is possible to add <param> elements corresponding to the attributes supported by the HTML 5 <video> element (<crossorigin>, <poster>, <preload>, <autoplay>, <mediagroup>, <loop>, <muted>, <controls>, <width>, <height>). In the above example, we have added a <param> element corresponding to the <width>, <controls> and <poster> HTML 5 attributes. Note that in the case of HTML 5 boolean attributes (<autoplay>, <loop>, <muted>, <controls>), the @value attribute of a <param> is not significant. For example, in the case of the above example, you could have specified "true", "on", "1", etc, instead of "yes".
If the <object> element has a <desc> child element, then this <desc> element is used to generate fallback content in case video is not supported. If the object element has no <desc> child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the video file. The <param> element corresponding to the <poster> HTML 5 attribute, if present, is used to generate a nicer automatic fallback content.
When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the output file.

Lightweight DITA

has an <video> element, so there is no need to use an <object> element. The equivalent of the above <object> example would be:

<video width="320">
  <video-poster value="media/video_poster.jpg"/>

  <media-controls value="true"/>

  <media-source value="media/video.mp4"/>
  <media-source value="media/video.ogv"/>
  <media-source value="media/video.webm"/>
</video>

§ Other uses of the `<object>` element

We have seen in previous sections how the <object> DITA element may be used to add audio and video to your DITA topics. In any case other than those described in previous sections, the <object> DITA element is converted to the equivalent <object> XHTML element. For example, if you want to add a YouTube video to your DITA topics, simply do it in DITA as you would do it in XHTML using the <object> element.

The XML source code corresponding to the above example is:

<p><object data="https://www.youtube.com/embed/C0DPdy98e4c"
           width="640" height="360">
     <desc><image href="media/youtube_icon.png"/> Watch this <xref format="html"
     href="https://youtu.be/C0DPdy98e4c" scope="external">test video</xref> on
     YouTube.</desc>
</object></p>

Notes:

If the <object> element has a <desc> child element, then this <desc> element is used to generate fallback content in case the media object is not supported. If the object element has no <desc> child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the media file.
When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the output file.

Chapter 8. Rich media content

§ SVG

Embedding SVG

§ MathML

Equation 8-1. Gauss's law in its differential form

Embedding MathML

§ TeX/LaTeX math

Tip

Embedding TeX math

§ Audio

§ Video

§ Other uses of the <object> element

§ Other uses of the `<object>` element