Images and Videos Source

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="tutorial"
      id="media">

<info>
  <link type="guide" xref="index"/>

  <revision version="0.1" date="2009-06-16" status="incomplete"/>

  <credit type="author copyright">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
    <years>2010</years>
  </credit>

  <include href="../../cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <desc>Add screenshots, screencasts, and other media to your Mallard documents.</desc>
</info>

<title>Images and Videos</title>

<note style="pmo-source">
<title>Learn by Example</title>
<p>This page was written in a Mallard extension format called Mallard Sites.
<link xref="media-src">Read the source markup</link> for this page to
learn Mallard from real-world examples.</p>
</note>

<p>A picture tells a thousand words, but only if those words describe
that picture.  Documentation often uses screenshots to highlight relevant
parts of an interface, or diagrams and charts to better illustrate some
information.  Furthermore, screencast videos are increasingly more common,
because they show user actions and program activity directly.</p>

<p>In this tutorial, you will learn how to insert images and videos into
your Mallard document.  You will also learn how to create figures with
titles and captions.</p>

<section id="images">
<title>Images</title>

<p>Use the <code xref="/1.1/mal_block_media">media</code>
element to add any type of media to your document, including images.
Specify that the media is an image by setting the <code>type</code>
attribute to <code>"image"</code>.  Use the <code>src</code> attribute
to provide the URL for the image.  Try this example by adding it as a
block element to a Mallard document; that is, add it where you would
normally add a paragraph.</p>

<example>
<code mime="application/xml"><![CDATA[
<media type="image" src="mallard-logo.png"/>
]]></code>
<media type="image" src="mallard-logo.png"/>
</example>

<p>You can also provide the size of the image with the <code>width</code>
and <code>height</code> attributes.  You can use these attributes to scale
the image to different dimensions.  The attribute values are numbers without
any units; they are always interpreted as pixels.</p>

<example>
<code mime="application/xml"><![CDATA[
<media type="image" src="mallard-logo.png" width="240" height="60"/>
]]></code>
<media type="image" src="mallard-logo.png" width="240" height="60"/>
</example>

<p>When you use the <code>media</code> element in a block context, it is
treated as a block element.  But you can also use the
<code xref="/1.1/mal_inline_media">media</code> element inline
to add images in running text, such as inside a paragraph.</p>

<example>
<code mime="application/xml"><![CDATA[
<p>Powered by <media type="image" src="mallard-badge.png"/></p>
]]></code>
<p>Powered by <media type="image" src="mallard-badge.png"/></p>
</example>

</section>

<section id="videos">
<title>Videos</title>

<p>You can add a video to your document in the same way you added an image.
Simply set the <code>type</code> attribute to <code>"video"</code> and point
the <code>src</code> attribute to the URL of your video.</p>

<example>
<code mime="application/xml"><![CDATA[
<media type="video" src="mallard-logo.webm"/>
]]></code>
<media type="video" src="mallard-logo.webm"/>
</example>

<note>
<p>When Mallard documents are converted to HTML, support for videos depends
on browser support for the HTML <code>video</code> tag.</p>
</note>

</section>

<section id="fallback">
<title>Fallback Content</title>

<p>Mallard is a source format.  It is designed to be easy to convert to other
formats that may be more suitable for particular needs.  Some types of media
are not possible in some target formats.  For example, a printed document can't
show a video.  A UNIX manual page can't show an image.  Even in a media-rich
online environment, alternative text content is helpful to blind users using
a screen reader.</p>

<p>Mallard allows you to specify fallback content by adding content inside
the <code>media</code> element.  What you can add depends on where you use
the <code>media</code> element.  If you use it as a block element, you can
add any block elements inside it, such as paragraphs or code blocks.</p>

<example>
<code mime="application/xml"><![CDATA[
<media type="image" src="mallard-logo.png">
  <p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
</media>
]]></code>
<!--
NOTE if you're viewing the source: We removed the actual media
element so that we get the fallback content instead.
-->
<p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
</example>

<p>If you use the <code>media</code> element as an inline element, you
can use text and any inline elements as fallback content.</p>

<example>
<code mime="application/xml"><![CDATA[
<p>Powered by <media type="image" src="mallard-badge.png">Mallard</media></p>
]]></code>
<!--
NOTE if you're viewing the source: We removed the actual media
element so that we get the fallback content instead.
-->
<p>Powered by Mallard</p>
</example>

<p>You can even use other <code>media</code> elements inside the fallback
content.  The fallback <code>media</code> elements can also have fallback
content.</p>

<example>
<code mime="application/xml"><![CDATA[
<media type="video" src="mallard-logo.ogv">
  <media type="image" src="mallard-logo.png">
    <p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
  </media>
</media>
]]></code>
<!--
NOTE if you're viewing the source: We removed the actual media
element so that we get the fallback content instead.
-->
<media type="image" src="mallard-logo.png">
<p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
</media>
</example>

<p>If you view this in a text-only environment, you will only see the
text fallback content.</p>

<example>
<p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
</example>

</section>

<section id="figures">
<title>Figures</title>

<p>Images are often accompanied by titles or captions.  Titles and captions
can help readers understand the image and refer to it later.  This is especially
important for diagrams and charts, where you may need to explain what certain
notations mean.  You can add a title or a caption using the
<code xref="/1.1/mal_block_figure">figure</code> element.</p>

<example>
<code mime="application/xml"><![CDATA[
<figure>
  <title>Mallard Logo</title>
  <desc>The Mallard logo is a question-mark-shaped duck head in a circle.</desc>
  <media type="image" src="mallard-logo.png"/>
</figure>
]]></code>
<figure>
  <title>Mallard Logo</title>
  <desc>The Mallard logo is a question-mark-shaped duck head in a circle.</desc>
  <media type="image" src="mallard-logo.png"/>
</figure>
</example>

<p>The <code xref="/1.1/mal_block_title">title</code> element
provides a title for the figure, while the
<code xref="/1.1/mal_block_desc">desc</code> element provides
a caption.  Both elements are optional, although you should use at least
one of them.  Note that both <code>title</code> and <code>desc</code>
take normal inline content, not paragraphs or other block content.
When you use a <code>media</code> element inside a <code>figure</code>
element, it is interpreted as a block element.  So any fallback content
must also be block content.</p>

<example>
<code mime="application/xml"><![CDATA[
<figure>
  <title>Mallard Logo</title>
  <desc>The Mallard logo is a question-mark-shaped duck head in a circle.</desc>
  <media type="image" src="mallard-logo.png">
    <p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
  </media>
</figure>
]]></code>
<figure>
<title>Mallard Logo</title>
<desc>The Mallard logo is a question-mark-shaped duck head in a circle.</desc>
<!--
NOTE if you're viewing the source: We removed the actual media
element so that we get the fallback content instead.
-->
<p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
</figure>
</example>

</section>

<section id="learnmore">
<title>Learn More</title>

<p>In this tutorial, you learned how to add images and videos with fallback
content, titles, and captions.  To learn more about media and figures, read
the specification pages and examples on
<link xref="/1.1/mal_block_media">block media</link>,
<link xref="/1.1/mal_inline_media">inline media</link>, and
<link xref="/1.1/mal_block_figure">figures</link>.</p>
</section>

</page>