[mallard] Flushing out media elements spec and implementation

3 files changed, 183 insertions, 51 deletions

diff --git a/doc/mallard/C/mal_block_media.xml b/doc/mallard/C/mal_block_media.xml
index 2a08347..c5fb407 100644
--- a/doc/mallard/C/mal_block_media.xml
+++ b/doc/mallard/C/mal_block_media.xml
@@ -4,7 +4,22 @@
 
 <info>
   <link type="guide" xref="mal_block#elements"/>
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <link type="seealso" xref="mal_inline_media"/>
+
+  <version number="0.1" date="2009-05-03" status="review"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm@gnome.org</email>
+  </credit>
+  <copyright>
+    <year>2008-2009</year>
+    <name>Shaun McCance</name>
+  </copyright>
+
+  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
+
+  <desc>Insert an image, video, or other multimedia object.</desc>
 </info>
 
 <title>Multimedia Objects</title>
@@ -30,6 +45,28 @@ the contents of a <code>media</code> element.  See <link xref="#processing"/>
 for details on how fallback elements are handled.</p>
 
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>style</code> attribute takes a space-separated list of
+    style hints.  Processing tools should adjust their behavior according to
+    those style hints they understand.</p></item>
+
+    <item><p>The <code>mime</code> attribute takes a valid MIME type for the
+    object that is being inserted.</p></item>
+
+    <item><p>The <code>media</code> element can have attributes from external
+    namespaces.  See <link xref="mal_attr_external"/> for more information
+    on external-namespace attributes on inline elements.</p></item>
+
+    <item><p>The <code>media</code> element may also be used in an inline context.
+    See <link xref="mal_inline_media"/> for more information.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
@@ -96,6 +133,15 @@ for details on how fallback elements are handled.</p>
 <!-- BEGIN comparison -->
 <section id="comparison">
   <title>Comparison to Other Formats</title>
+
+  <p>The <code>media</code> element can be used in place of the DocBook elements
+  <code xref="http://www.docbook.org/tdg/en/html/audiooobject.html">audioobject</code>,
+  <code xref="http://www.docbook.org/tdg/en/html/imageobject.html">imageobject</code>, and
+  <code xref="http://www.docbook.org/tdg/en/html/videoobject.html">videoobject</code>.
+  DocBook uses the
+  <code xref="http://www.docbook.org/tdg/en/html/mediaobject.html">mediaobject</code>
+  element to provide alternative objects.  In Mallard, alternative objects are
+  nested, obviating the need for a container element.</p>
 </section>
 <!-- END comparison -->
 
diff --git a/doc/mallard/C/mal_inline_media.xml b/doc/mallard/C/mal_inline_media.xml
index 8a96377..4fc37ee 100644
--- a/doc/mallard/C/mal_inline_media.xml
+++ b/doc/mallard/C/mal_inline_media.xml
@@ -5,65 +5,131 @@
 <info>
   <link type="guide" xref="mal_inline#elements"/>
 
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <version number="0.1" date="2009-05-03" status="review"/>
 
-  <desc>Insert images, video, and sound into your document.</desc>
+  <desc>Insert an image, video, or other multimedia object.</desc>
 </info>
 
-<title>Multimedia Objects</title>
+<title>Inline Multimedia Objects</title>
 
 <synopsis><code mime="application/relax-ng-compact-syntax">
-mal_inline_media = element media {
-  mal_inline_media_container |
-  mal_inline_media_application |
-  mal_inline_media_audio |
-  mal_inline_media_image |
-  mal_inline_media_text |
-  mal_inline_media_video
-}
-mal_inline_media_container = element media {
-  attribute style { xsd:NMTOKENS } ?,
-  attribute * - (mal:* | local:*) { text } *,
-  ( mal_inline_media_application |
-    mal_inline_media_audio |
-    mal_inline_media_image |
-    mal_inline_media_text |
-    mal_inline_media_video
-  ) +
-}
-mal_inline_media_audio = element media {
-  attribute type { "audio" },
-  attribute mime { text } ?,
-  attribute src { text },
-  attribute style { xsd:NMTOKENS } ?,
-  attribute * - (mal:* | local:*) { text } *,
-}
-mal_inline_media_application = element media {
-  attribute type { "application" },
-  attribute mime { text } ?,
-  attribute src { text },
-  attribute style { xsd:NMTOKENS } ?,
-  attribute * - (mal:* | local:*) { text } *,
-}
-mal_inline_media_image = element media {
-  attribute type { "image" },
-  attribute mime { text } ?,
-  attribute src { text },
-  attribute style { xsd:NMTOKENS } ?,
-  attribute * - (mal:* | local:*) { text } *,
-}
-mal_inline_media_text = element media {
-  attribute type { "text" },
-  attribute style { xsd:NMTOKENS } ?,
-  attribute * - (mal:* | local:*) { text } *,
-}
-mal_inline_media_video = element media {
-  attribute type { "video" },
+mal_block_media = element media {
+  <link xref="mal_attr_link">mal_attr_link</link> ?,
+  attribute type { "image" | "video" | "audio" | "application" } ?,
   attribute mime { text } ?,
   attribute src { text },
+  attribute height { text },
+  attribute width { text },
   attribute style { xsd:NMTOKENS } ?,
   attribute * - (mal:* | local:*) { text } *,
+
+  <link xref="mal_inline">mal_inline</link>
 }
 </code></synopsis>
 
+<p>Use the <code>media</code> element to insert an image, video, or other
+multimedia object into your document.  Since not all display tools will be
+able to display all types of objects, you can provide fallback elements in
+the contents of a <code>media</code> element.  See <link xref="#processing"/>
+for details on how fallback elements are handled.</p>
+
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>style</code> attribute takes a space-separated list of
+    style hints.  Processing tools should adjust their behavior according to
+    those style hints they understand.</p></item>
+
+    <item><p>The <code>mime</code> attribute takes a valid MIME type for the
+    object that is being inserted.</p></item>
+
+    <item><p>The <code>media</code> element can link to other pages or documents.
+    See <link xref="mal_attr_link"/> for more information.</p></item>
+
+    <item><p>The <code>media</code> element can have attributes from external
+    namespaces.  See <link xref="mal_attr_external"/> for more information
+    on external-namespace attributes on inline elements.</p></item>
+
+    <item><p>The <code>media</code> element may also be used in a block context.
+    See <link xref="mal_block_media"/> for more information.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Use <code>media</code> to insert an image into your document:</p>
+
+  <example>
+    <code><![CDATA[
+<p><media type="image" mime="image/png" src="figures/mallard.png">
+Drake, the Mallard mascot
+</media></p>
+]]></code>
+    <p><media type="image" mime="image/png" src="figures/mallard.png">
+      Drake, the Mallard mascot
+    </media></p>
+  </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>When a <code>media</code> element occurs in an inline context, it should be
+  displayed as an inline element.  The exact rendering of a <code>media</code>
+  element will depend on the <code>type</code> and <code>mime</code> attributes.
+  Display tools may need to add controls for audio and video objects.</p>
+
+  <p>The <code>application</code> type is intended for embedding interactive
+  applications in documents.  There are currently no specific recommendations
+  for displaying application objects.  Behavior may vary according to the
+  type of application being embedded.</p>
+
+  <p>Some display tools will not be able to display all types of objects.
+  For example, a printed document will not be able to display video or play
+  back audio.  Even when a display tool can display the type of object, it
+  may not be able to work with the given MIME type for technical or other
+  reasons.</p>
+
+  <p>When a display tool cannot display a <code>media</code> element, it
+  should display the child elements of the element, as if the <code>media</code>
+  element itself were replaced by its children.  The child elements may consist
+  of simply another <code>media</code> element referencing a different type of
+  content.  When processing any child <code>media</code> elements, display tools
+  may need to fall back further to their child elements.</p>
+
+  <p>In some display media, multimedia objects can have alternate text.  This
+  may be displayed when a user hovers over the object, or it may be provided
+  to assistive technologies.  When displaying in such a medium, display tools
+  should extract the text value of a <code>media</code> element by processing
+  its child elements, and recursively processing any child <code>media</code>
+  elements, as if it can not display any types of <code>media</code> elements.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+
+  <p>The <code>media</code> element can be used in place of the DocBook elements
+  <code xref="http://www.docbook.org/tdg/en/html/audiooobject.html">audioobject</code>,
+  <code xref="http://www.docbook.org/tdg/en/html/imageobject.html">imageobject</code>, and
+  <code xref="http://www.docbook.org/tdg/en/html/videoobject.html">videoobject</code>.
+  DocBook uses the
+  <code xref="http://www.docbook.org/tdg/en/html/inlinemediaobject.html">inlinemediaobject</code>
+  element to provide alternative objects.  In Mallard, alternative objects are
+  nested, obviating the need for a container element.</p>
+</section>
+<!-- END comparison -->
+
+
 </page>
diff --git a/xslt/mallard/html/mal2html-media.xsl b/xslt/mallard/html/mal2html-media.xsl
index 10531d6..20308b5 100644
--- a/xslt/mallard/html/mal2html-media.xsl
+++ b/xslt/mallard/html/mal2html-media.xsl
@@ -30,7 +30,7 @@ REMARK: Describe this module
 
 <!-- == Matched Templates == -->
 
-<!-- = mal2html.block.mode % media/image = -->
+<!-- = mal2html.block.mode % media = -->
 <xsl:template mode="mal2html.block.mode" match="mal:media">
   <xsl:param name="first_child" select="not(preceding-sibling::*)"/>
   <xsl:choose>
@@ -73,4 +73,24 @@ REMARK: Describe this module
   </xsl:choose>
 </xsl:template>
 
+<!-- = mal2html.inline.mode % media = -->
+<xsl:template mode="mal2html.inline.mode" match="mal:media">
+  <xsl:choose>
+    <xsl:when test="@type = 'image'">
+      <span class="media media-image">
+        <img src="{@src}">
+          <xsl:copy-of select="@height"/>
+          <xsl:copy-of select="@width"/>
+          <xsl:attribute name="alt">
+            <xsl:value-of select="."/>
+          </xsl:attribute>
+        </img>
+      </span>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:apply-templates mode="db2html.inline.mode"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
 </xsl:stylesheet>