Section 4.4. Rich media content

4.4. Rich media content

This chapter explains how to add SVG, MathML, audio, video and Flash animations to your DITA topics and how ditac processes this rich media content in the case where the output format supports rich media (e.g. XHTML 5, EPUB 3) and also in the case where the output format does not support rich media (e.g. XHTML 1, PDF, RTF).

Note

XMLmind XML Editor has buttons in its DITA Topic tool bar which allows to easily insert any of the elements described in this chapter.

Figure 7. The menu displayed by the "Add image" button

Figure 8. The menu displayed by the "Add MathML equation" button

Figure 9. The menu displayed by the "Insert media object" button

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>

Notes:

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 graphics in a DITA document as this is likely to cause many validation problems.
Only the following screen formats may contain SVG: XHTML 5, XHTML 5 Web Help and EPUB 3. Note that only modern web browsers support XHTML 5 and XHTML 5 Web Help. Very few EPUB readers (e.g. iBooks) support EPUB 3.
All XSL-FO based formats (PDF, RTF, DOCX, etc) support SVG whatever the XSL-FO processor you may use.

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:

\nabla, E = \frac{ρ}{ε_{0}}

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:

{\begin{matrix} \nabla\times E = - \frac{\partial B}{\partial t} \\ \nabla\times B = μ_{0} J + μ_{0} ε_{0} \frac{\partial E}{\partial t} \end{matrix}

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>

Notes:

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

There is an option to number <equation-figure> elements having a <title>. Example:

Equation 1. Gauss's law in its differential form

\nabla, E = \frac{ρ}{ε_{0}}

<equation-block> elements containing a empty <equation-number> are automatically numbered. Example:

\nabla, E = \frac{ρ}{ε_{0}}

(1)

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.

Only the following screen formats may contain MathML: XHTML 5, XHTML 5 Web Help and EPUB 3. Most modern web browsers (Firefox, Chrome) support XHTML 5 and XHTML 5 Web Help containing MathML. Very few EPUB readers (e.g. iBooks) support EPUB 3.
XSL-FO based formats(PDF, RTF, DOCX, etc) support MathML depending on the XSL-FO processor you use:
- Apache FOP requires you to download and install the the JEuclid FOP plug-in .
- RenderX XEP does not support MathML.
- Antenna House Formatter supports MathML as an option.
- XMLmind XSL-FO Converter supports MathML out of the box.

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>

Flash animation

Use the <object> DITA element to add Adobe® Flash® animations to your DITA topics. Example:

(You may have to right-click on the above screenshot and select Play from the Flash popup menu to replay the animation.)

The XML source code corresponding to the above example is:

<p><object data="animation.swf" 
           type="application/x-shockwave-flash" 
           width="431" height="123">
    <param name="movie" value="animation.swf"
           valuetype="ref" type="application/x-shockwave-flash"/>

    <param name="menu" value="true"/>
    <param name="quality" value="low"/>
</object></p>

Notes:

The @data, @type, @width and @height attributes are required. The param name=movie child element having the same value as attribute @data is required too.
You may add any other <param> child element supported by the Flash object. In the above example, you'll find menu and quality in addition to required movie.
If the <object> element has a <desc> child element, then this <desc> element is used to generate fallback content in case Flash 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 .swf file.
When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the output file.

Other uses of the `<object>` element

We have seen in previous sections how the <object> DITA element may be used to add audio, video and Adobe® Flash® animations 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.

4.4. Rich media content

Note

Figure 7. The menu displayed by the "Add image" button

Figure 8. The menu displayed by the "Add MathML equation" button

Figure 9. The menu displayed by the "Insert media object" button

SVG

MathML

Equation 1. Gauss's law in its differential form

Audio

Video

Flash animation

Other uses of the <object> element

Other uses of the `<object>` element