[gnome-doc-utils/mallard] [mallard] Updates to media processing

[Shaun McCance <shaunm src gnome org>]

commit fbb0711182c22a665d92e1842472fc341cfe4bda
Author: Shaun McCance <shaunm gnome org>
Date:   Sun May 3 00:19:40 2009 -0500

    [mallard] Updates to media processing
    
    I'm going back to my original idea of nested chaining, instead of
    using a container element to list fallbacks.  I thought there were
    logistical problems with using nested elements both for alternate
    media and for text fallback, until I realized there aren't.
---
 doc/mallard/C/mal_block_media.xml    |   45 ++++++++++++++++++++++++++++++++-
 xslt/mallard/html/mal2html-media.xsl |   45 ++++++++++++++++++++++++++++++----
 2 files changed, 83 insertions(+), 7 deletions(-)

diff --git a/doc/mallard/C/mal_block_media.xml b/doc/mallard/C/mal_block_media.xml
index 8ff837e..2a08347 100644
--- a/doc/mallard/C/mal_block_media.xml
+++ b/doc/mallard/C/mal_block_media.xml
@@ -14,6 +14,8 @@ mal_block_media = element media {
   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 } *,
 
@@ -36,9 +38,13 @@ for details on how fallback elements are handled.</p>
 
   <example>
     <code><![CDATA[
-<media type="image" mime="image/png" src="figures/mallard.png"/>
+<media type="image" mime="image/png" src="figures/mallard.png">
+<p>Drake, the Mallard mascot</p>
+</media>
 ]]></code>
-    <media type="image" mime="image/png" src="figures/mallard.png"/>
+    <media type="image" mime="image/png" src="figures/mallard.png">
+      <p>Drake, the Mallard mascot</p>
+    </media>
   </example>
 
 </section>
@@ -48,6 +54,41 @@ for details on how fallback elements are handled.</p>
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
+
+  <p>When a <code>media</code> element occurs in a block context, it should be
+  displayed as a block 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>Frequently, the children of a <code>media</code> element will be a single
+  block element, such as another <code>media</code> element or a <code>p</code>
+  element.  Note, however, that this is not required, and fallback rendering
+  may involve displaying several block 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 -->
 
diff --git a/xslt/mallard/html/mal2html-media.xsl b/xslt/mallard/html/mal2html-media.xsl
index 3aae961..10531d6 100644
--- a/xslt/mallard/html/mal2html-media.xsl
+++ b/xslt/mallard/html/mal2html-media.xsl
@@ -31,11 +31,46 @@ REMARK: Describe this module
 <!-- == Matched Templates == -->
 
 <!-- = mal2html.block.mode % media/image = -->
-<xsl:template mode="mal2html.block.mode"
-              match="mal:media[ type='image']">
-  <div class="media media-image">
-    <img src="{ src}"/>
-  </div>
+<xsl:template mode="mal2html.block.mode" match="mal:media">
+  <xsl:param name="first_child" select="not(preceding-sibling::*)"/>
+  <xsl:choose>
+    <xsl:when test="@type = 'image'">
+      <div>
+        <xsl:attribute name="class">
+          <xsl:text>media media-image</xsl:text>
+          <xsl:if test="$first_child">
+            <xsl:text> first-child</xsl:text>
+          </xsl:if>
+        </xsl:attribute>
+        <img src="{ src}">
+          <xsl:copy-of select="@height"/>
+          <xsl:copy-of select="@width"/>
+          <xsl:attribute name="alt">
+            <!-- FIXME: This is not ideal.  Nested block container elements
+                 will introduce lots of garbage whitespace.  But then, XML
+                 processors are supposed to normalize whitespace in attribute
+                 values anyway.  Ideally, we'd have a set of modes for text
+                 conversion.  That'd probably be best handled in a set of
+                 mal2text stylesheets.
+            -->
+            <xsl:for-each select="mal:*">
+              <xsl:if test="position() &gt; 1">
+                <xsl:text>&#x000A;</xsl:text>
+              </xsl:if>
+              <xsl:value-of select="string(.)"/>
+            </xsl:for-each>
+          </xsl:attribute>
+        </img>
+      </div>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:for-each select="mal:*">
+        <xsl:apply-templates mode="db2html.block.mode" select=".">
+          <xsl:with-param name="first_child" select="position() = 1 and $first_child"/>
+        </xsl:apply-templates>
+      </xsl:for-each>
+    </xsl:otherwise>
+  </xsl:choose>
 </xsl:template>
 
 </xsl:stylesheet>