1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_block_media">
<info>
<link type="seealso" xref="mal_inline_media"/>
<revision version="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>
<synopsis><code mime="application/relax-ng-compact-syntax">
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 } *,
<link xref="mal_block">mal_block</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>
<item><p>The <code>media</code> element can contain any
<link xref="mal_block">general block content</link>. The content is only
used as a fallback or alternative.</p></item>
<item><p>The <code>media</code> element can occur in any
general block context, including inside
<link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
and certain <link xref="mal_block">block elements</link>.</p></item>
<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_external"/> for more information
on external-namespace attributes.</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>
<p>Use <code>media</code> to insert an image into your document:</p>
<example>
<code><![CDATA[
<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">
<p>Drake, the Mallard mascot</p>
</media>
</example>
</section>
<!-- END examples -->
<!-- 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 -->
<!-- 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 -->
</page>
|
