mep/mep0002: Use title case
[projectmallard:projectmallard.git] / mep / mep0002.page
1 <page xmlns="http://projectmallard.org/1.0/"
2       type="topic" style="mep"
3       version="1.0"
4       id="mep0002">
5
6 <info>
7   <link type="guide" xref="index" group="1.1"/>
8
9   <credit type="author copyright">
10     <name>Shaun McCance</name>
11     <email>shaunm@gnome.org</email>
12     <years>2013</years>
13   </credit>
14
15   <include href="../cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude">
16     <fallback/>
17   </include>
18
19   <revision date="2013-10-20" docversion="1.1" status="incomplete"/>
20   <revision date="2014-02-01" docversion="1.1" status="proposed"/>
21
22   <title type="text">Block info Element</title>
23   <title type="link">MEP-0002: Block <code>info</code> Element</title>
24
25   <desc>Allow the <code>info</code> element on formal block elements and
26   block <code>media</code> element to provide metadata about them.</desc>
27 </info>
28
29 <title>MEP-0002</title>
30 <subtitle>Block <code>info</code> Element</subtitle>
31
32 <p style="lead">This page proposes allowing the <code>info</code> element
33 to be used on certain block elements, possibly with a modified content model.
34 This allows finer-grained metadata and opens more possibilities for
35 extensions.</p>
36
37 <links type="section"/>
38
39
40 <section id="background">
41   <title>Background</title>
42
43   <p>Mallard provides an <code>info</code> element that can be placed at the
44   beginning of a <code>page</code> or <code>section</code> element and may
45   contain any number of informational elements to provide automatic linking,
46   alternate titles, credits and copyright information, and much more.</p>
47
48   <p>Sometimes it's useful to provide some of this information for a smaller
49   portion of a page. For example, you may wish to credit the programmer who
50   contributed a code block, or the illustrator who created an image. You might
51   also want to provide alternate titles, even without linking, as these can be
52   used by extensions such as <link xref="/ui/1.0/ui_expanded">UI Expanders</link>.</p>
53 </section>
54
55
56 <section id="proposal">
57   <title>Proposal</title>
58
59   <p>This page proposes alloing the <code>info</code> element as an optional
60   first element in any block element that contains other block elements, as
61   well as any block elements with structured content. As of Mallard 1.0, that
62   includes
63   <code xref="/1.0/mal_block_media">media</code>,
64   <code xref="/1.0/mal_block_comment">comment</code>,
65   <code xref="/1.0/mal_block_example">example</code>,
66   <code xref="/1.0/mal_block_figure">figure</code>,
67   <code xref="/1.0/mal_block_listing">listing</code>,
68   <code xref="/1.0/mal_block_note">note</code>,
69   <code xref="/1.0/mal_block_quote">quote</code>,
70   <code xref="/1.0/mal_block_synopsis">synopsis</code>,
71   <code xref="/1.0/mal_block_list">list</code>,
72   <code xref="/1.0/mal_block_steps">steps</code>,
73   <code xref="/1.0/mal_block_terms">terms</code>,
74   <code xref="/1.0/mal_block_tree">tree</code>,
75   and <code xref="/1.0/mal_block_table">table</code>.</p>
76
77   <p>As with the existing <code>info</code> element, there are no processing
78   expectations associated with the <code>info</code> element used on block
79   elements. Certain informational elements may introduce processing expectations
80   of their own. In Mallard 1.0, the only informational elements that normatively
81   affect page processing are related to linking. This page does not propose
82   adding block elements to automatic linking (although this proposal would be
83   a prerequisite for doing so).</p>
84 </section>
85
86
87 <section id="examples">
88   <title>Examples</title>
89
90   <p>Specify that a code block may be reused under the terms of the MIT license
91   as published by the OSI.</p>
92
93   <example>
94     <code mime="application/xml"><![CDATA[<listing>
95 <info>
96 <license href="http://opensource.org/licenses/MIT"/>
97 </info>
98 <code>
99 def match_locale(extrange, locale):
100     # Extended filtering for extended language ranges as                                                    
101     # defined by RFC4647, part of BCP47.                                                                    
102     # http://tools.ietf.org/html/rfc4647#section-3.3.2                                                      
103     rangelist = [x.lower() for x in extrange.split('-')]
104     localelist = [x.lower() for x in locale.split('-')]
105     if rangelist[0] not in ('*', localelist[0]):
106         return False
107     rangei = localei = 0
108     while rangei < len(rangelist):
109         if rangelist[rangei] == '*':
110             rangei += 1
111             continue
112         if localei >= len(localelist):
113             return False
114         if rangelist[rangei] in ('*', localelist[localei]):
115             rangei += 1
116             localei += 1
117             continue
118         if len(localelist[localei]) == 1:
119             return False
120         localei += 1
121     return True
122 </code>
123 </listing>]]></code>
124   </example>
125
126   <p>Give credit to illustrators and videographers.</p>
127
128   <example>
129     <code mime="application/xml"><![CDATA[
130 <media type="image" src="graph.png">
131   <info>
132     <credit type="illustrator copyright">
133       <name>Rupert</name>
134       <email>rupert@example.com</email>
135       <years>2013</years>
136     </credit>
137   </info>
138 </media>]]></code>
139     <code mime="application/xml"><![CDATA[
140 <media type="video" src="presentation.webm">
141   <info>
142     <credit type="videographer copyright">
143       <name>Wanda</name>
144       <email>wanda@example.com</email>
145       <years>2013</years>
146     </credit>
147   </info>
148 </media>]]></code>
149   </example>
150
151   <p>Provide an alternate title for when a figure is collapsed using
152   <link xref="/ui/1.0/ui_expanded">UI Expanders</link>.</p>
153
154   <example>
155     <code mime="application/xml"><![CDATA[
156 <figure ui:expanded="false">
157   <info>
158     <title type="ui:collapsed">Show Chart</title>
159   </info>
160   <title>Chart</title>
161   <media type="image" src="chart.png"/>
162 </figure>
163 ]]></code>
164   </example>
165 </section>
166
167
168 <section id="compatibility">
169   <title>Compatibility and Fallback</title>
170
171   <p>This proposal makes no backwards-incompatible changes. That is, any page
172   written in a version prior to the implementation of this proposal will work
173   exactly the same in a processing tool that implements this proposal.</p>
174
175   <p>This proposal adds an element where a block element may be expected.
176   Normally, if a new block element were to be added, its fallback behavior
177   would be subject to the default <link xref="/1.0/mal_block#processing">block
178   context fallback behavior</link>. This behavior is mostly suitable for this
179   addition, although there is potential for a multi-purpose element to be
180   accidentally processed in restricted block context.</p>
181
182   <p>However, the <link xref="/1.0/mal_info#processing">processing expectations
183   for the <code>info</code> element</link> explicitly say "If an <code>info</code>
184   element appears in any context other than as the first element of a page or
185   section, it is ignored." Therefore, the fallback behavior for any conformant
186   processor that does not implement this proposal is to ignore the additional
187   element, which is the desired behavior.</p>
188
189   <p>This page also proposes allowing the <code>info</code> element in list
190   and table elements. These elements do not take block content, but rather have
191   structured content specific to each element. None of these elements specifies
192   the fallback behavior for unrecognized elements. All known implementations
193   ignore unrecognized elements, so this change is considered safe.</p>
194 </section>
195
196
197 <section id="comparison">
198   <title>Comparison to Other Formats</title>
199
200   <p>Docbook 5 allows the generic
201   <code href="http://www.docbook.org/tdg51/en/html/titleonly.info.html">info</code>
202   element to be used on many block-level elements, similar to this proposal.
203   DocBook 4 contained more specialized info elements, including the
204   <code href="http://www.docbook.org/tdg/en/html/blockinfo.html">blockinfo</code>
205   element for many block elements and the
206   <code href="http://www.docbook.org/tdg/en/html/objectinfo.html">objectinfo</code>
207   element for media objects.</p>
208
209   <p>DITA does not contain an element to record metadata about block elements,
210   and only allows the
211   <code href="http://docs.oasis-open.org/dita/v1.2/cd03/spec/langref/prolog.html">prolog</code>
212   elements on
213   <code href="http://docs.oasis-open.org/dita/v1.2/cd03/spec/langref/topic.html">topic</code>
214   and derivative elements.</p>
215 </section>
216
217 </page>