Which DITA element can be used to embed YouTube videos?

Question 1

I am not sure if this is the correct way of doing this, but this does seem to work and is quite easy to work with. After further reading it seems that the <object> element is designed for embedding videos, media and ActiveX controls.

On initial inspection the process of embedding YouTube videos seems rather complicated. Several blogs/forums make reference to copying the (old-style) YouTube embed code and ditching the parts which are incompatible with DITA. Unfortunately this technique is reported to cause playback issues in some situations.

So instead I decided to experiment with using the <object> element but with customised stylesheets making this entire process easier. I am not sure if this approach is technically valid, input would be appreciated on that point.

@type - Specify a value of "youtube" to trigger custom XSL rendering.
@data - YouTube video ID can be copied from embed code.
@width (optional) - Width of YouTube video in browser, defaults to 600px.
@height (optional) - Height of YouTube video in browser, defaults to 450px.

Here is an example of a video embed using this technique:

<!-- DITA markup -->
<fig audience="web">
    <title>YouTube 101: How to Find What's Hot on YouTube</title>
    <object type="youtube" data="FEyRza0rJyI">
        <desc>This video explains how to tap into the cultural zeitgeist happening on YouTube right now.</desc>
    </object>
</fig>

In order to make this work it is necessary to alter the way in which the XHTML output is generated. Fortunately this is extremely easy with DITA Converter (aka Ditac) by XML Mind. I simply added the following to my XSL customisation stylesheet:

<!-- Customize html output (works with DITA Converted by XML Mind) -->
<xsl:template match="*[contains(@class,' topic/object ') and @type='youtube']">
    <iframe src="http://www.youtube-nocookie.com/embed/{@data}?rel=0" frameborder="0" allowfullscreen="allowfullscreen">
        <xsl:attribute name="width" select="if (@width) then @width else '600'"/>
        <xsl:attribute name="height" select="if (@height) then @height else '450'"/>
        <xsl:call-template name="commonAttributes"/>
        <xsl:call-template name="namedAnchor"/>
    </iframe>
</xsl:template>

In my case I am only interested in embedding videos for web based content, and for this reason adding the @audience attribute is sufficient. But it would be easy to create an alternative output for printed media with perhaps a URL and the description text.

Question 2

Your suggested override is perfectly fine, Lea. The attribute mappings you showed are appropriate for the kind of data they pass through. You could over-engineer it by specializing a closer match to the current YouTube interfaces, but since they are likely to change again, this is a case where simple documentation of the approach is fine. In fact, you may be able to use the CSS before: pseudo-element (for example, see Insert special character using :before pseudo class in css) in XML Mind editor to inform users what data to put where (these behave like field labels for forms, in effect). Your example for overriding this usage of in Ditac closely models the way someone could adapt DITA OT transforms as well.

Question 3

The DITA for Publishers project (http://dita4publishers.sourceforge.net) provides a domain that specializes so that it parallels the HTML5 <video> element as closely as possible within the constraints of DITA specialization. The markup looks like this:

<fig
  outputclass="image">
  <d4p_video
    id="E5123_026.mp4"
    width="300"
    height="300">
    <d4p_video_poster
      value="../images/E5123_026_poster.png"/>
    <d4p_video_source
      value="../images/E5123_026.mp4"
      type="video/mp4"/>
  </d4p_video>
</fig>

The markup is defined in the d4p_mediaDomain. The DITA for Publishers project includes support for generating HTML5 video markup from this markup for HTML-based outputs (HTML, EPUB, etc.).

Question 4

The following markup works correctly in DITA-OT 1.5.4 and 1.7.2 (presumably everything in between):

<object width="640" height="360" data="//www.youtube.com/embed/vwh93zo7_oU?rel=0">
    <param name="src" value="//www.youtube.com/embed/vwh93zo7_oU?rel=0"/>
    <param name="movie" value="//www.youtube.com/embed/vwh93zo7_oU?rel=0"/>
    <param name="allowFullScreen" value="true"/>
    <param name="allowscriptaccess" value="always"/>
</object>

Obviously, substitute the ID of your video in all three places — I used a video that is part of our documentation so you'd have a working example.

The @width & @height attributes define the size of the box in which the video is shown.
The @data attribute and the first two <param> elements specify the link to the video. For cross-browser compatibility, include all three.
The last two <param> elements specify optional behaviors you want to allow for the video. You might not need them.

It would be possible to create a specialization that would reduce the needed markup, but in our case we do not include enough videos to justify the effort.

Question 5

Lea -- just one note, you can also embed Flash content in PDF (like for instance a youtube video player written in Flash with link to the video). I have not looked for a candidate but I am sure they exist. if the PDF rendering engine you use supports embedding RichMedia Annotations in PDF, you can place the interactive Flash right into the PDF.