diff options
author | Shaun McCance <shaunm@gnome.org> | 2009-05-19 13:47:26 -0500 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2009-05-19 13:47:26 -0500 |
commit | 5e1f23d4285564258ab8c9c43ec2c7b33853d528 (patch) | |
tree | 374296fbe4f8b9b665beb64014692d12935e3363 | |
parent | f2c9bbffe57e290b538c8a3237b4f663dd8c08f7 (diff) | |
download | gnome-doc-utils-5e1f23d4285564258ab8c9c43ec2c7b33853d528.tar.gz |
[mallard] Finishing block_figure and block_desc
-rw-r--r-- | doc/mallard/C/mal_block.xml | 1 | ||||
-rw-r--r-- | doc/mallard/C/mal_block_desc.xml | 78 | ||||
-rw-r--r-- | doc/mallard/C/mal_block_figure.xml | 74 |
3 files changed, 135 insertions, 18 deletions
diff --git a/doc/mallard/C/mal_block.xml b/doc/mallard/C/mal_block.xml index 9078302..32c2865 100644 --- a/doc/mallard/C/mal_block.xml +++ b/doc/mallard/C/mal_block.xml @@ -146,7 +146,6 @@ mal_block_list = ( <!-- BEGIN other --> <section id="other"> <info> - <title type="link">Other Block Elements</title> <link type="topic" xref="mal_title"/> <link type="topic" xref="mal_subtitle"/> <link type="topic" xref="mal_block_desc"/> diff --git a/doc/mallard/C/mal_block_desc.xml b/doc/mallard/C/mal_block_desc.xml index dca52d9..789e206 100644 --- a/doc/mallard/C/mal_block_desc.xml +++ b/doc/mallard/C/mal_block_desc.xml @@ -3,7 +3,11 @@ id="mal_block_desc"> <info> - <version number="0.1" date="2009-04-19" status="incomplete"/> + <link type="seealso" xref="mal_block_figure"/> + <link type="seealso" xref="mal_block_listing"/> + <link type="seealso" xref="mal_block_synopsis"/> + + <version number="0.1" date="2009-05-19" status="review"/> <credit type="author"> <name>Shaun McCance</name> @@ -16,7 +20,7 @@ <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> - <desc>FIXME</desc> + <desc>Provide a caption for a formal block element.</desc> </info> <title>Block Descriptions</title> @@ -36,17 +40,45 @@ The description provided by <code>desc</code> is formatted as a caption for the formal element.</p> +<!-- BEGIN notes --> +<section id="notes"> + <title>Notes</title> + <list type="bullet"> + <item><p>The <code>desc</code> element can contain a mixture of text and + any <link xref="mal_inline">general inline elements</link>.</p></item> + + <item><p>The <code>desc</code> element can occur in the formal block elements + <code xref="mal_block_figure">figure</code>, + <code xref="mal_block_listing">listing</code>, and + <code xref="mal_block_synopsis">synopsis</code>.</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>desc</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>desc</code> element can also be used in an informational + context. See <link xref="mal_info_desc"/> for more information.</p></item> + </list> +</section> +<!-- END notes --> + + <!-- BEGIN examples --> <section id="examples"> <title>Examples</title> - <p>Use <code>desc</code> to provide a caption for a figure:</p> + <p>Use <code>desc</code> to provide a caption for a + <link xref="mal_block_figure">figure</link>:</p> <example> <code><![CDATA[ <figure> - <media type="image" mime="image/png" src="figures/mallard.png"/> <desc>Drake, the Mallard mascot</desc> + <media type="image" mime="image/png" src="figures/mallard.png"/> </figure> ]]></code> <figure> @@ -55,7 +87,33 @@ for the formal element.</p> </figure> </example> - <p>More exaples of figures can be found on the page <link xref="mal_block_figure"/>.</p> + <p>Use <code>desc</code> to provide a caption for a + <link xref="mal_block_figure">listing</link>:</p> + + <example> + <code><![CDATA[ +<listing> + <desc>A first Mallard page</desc> + <code><![CDATA[ +<page xmlns="http://www.gnome.org/~shaunm/mallard" + type="guide" + id="index"> + <!-- Content goes here --> +</page>]]]>]><![CDATA[</code> +</listing>]]></code> + <listing> + <desc>A first Mallard page</desc> + <code><![CDATA[ +<page xmlns="http://www.gnome.org/~shaunm/mallard" + type="guide" + id="index"> + <!-- Content goes here --> +</page>]]></code> + </listing> + </example> + + <p>More exaples can be found on the pages <link xref="mal_block_figure"/>, + <link xref="mal_block_listing"/>, and <link xref="mal_block_synopsis"/>.</p> </section> <!-- END examples --> @@ -65,14 +123,12 @@ for the formal element.</p> <title>Processing Expectations</title> <p>The exact display of a description will depend on how the enclosing formal - element is displayed. A description is a block of text that should be displayed + element is displayed. A description is a block of text that is displayed directly above or below the normal contents of the enclosing element.</p> - <p>Display tools should attempt to display the description in a way that makes it - clear that it belongs to the enclosing formal element. For example, if a display - tool draws a frame around an enclosing figure, it may choose to place the description - inside that frame. If the formal element is indented from its enclosing block, the - description should also be at the same indentation level.</p> + <p>A description should be displayed in a way that makes its role clearn and + which clearly distinguishes it from the normal block content of the enclosing + element.</p> </section> <!-- END processing --> diff --git a/doc/mallard/C/mal_block_figure.xml b/doc/mallard/C/mal_block_figure.xml index 2920eb0..a9ad7f1 100644 --- a/doc/mallard/C/mal_block_figure.xml +++ b/doc/mallard/C/mal_block_figure.xml @@ -3,7 +3,23 @@ id="mal_block_figure"> <info> - <version number="0.1" date="2007-02-21" status="stub"/> + <link type="seealso" xref="mal_block_media"/> + <link type="seealso" xref="mal_block_listing"/> + + <version number="0.1" date="2009-05-19" 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>Provide a title or caption for a multimedia object.</desc> </info> <title>Figures</title> @@ -19,11 +35,11 @@ mal_block_figure = element figure { } </code></synopsis> -<comment> - <cite date="2006-11-16"><name>Shaun McCance</name></cite> - <p>Add explanation, examples, processing expectations</p> - <p>A way to float right, a'la wikipedia?</p> -</comment> +<p>Use the <code>figure</code> element to provide a title or caption for a +<link xref="mal_block_media">multimedia object</link> or other block object. +To provide a title for the contents of a file, such as a +<link xref="mal_block_code">code block</link>, use the +<code xref="mal_block_listing">listing</code> element instead.</p> <!-- BEGIN notes --> <section id="notes"> @@ -50,4 +66,50 @@ mal_block_figure = element figure { </section> <!-- END notes --> +<!-- BEGIN examples --> +<section id="examples"> + <title>Examples</title> + + <p>Use <code>figure</code> to provide a title and caption for an image:</p> + + <example> + <code><![CDATA[ +<figure> + <title>Drake</title> + <desc>Drake is the Mallard mascot.</desc> + <media type="image" mime="image/png" src="figures/mallard.png"/> +</figure> +]]></code> + <figure> + <title>Drake</title> + <desc>Drake is the Mallard mascot.</desc> + <media type="image" mime="image/png" src="figures/mallard.png"/> + </figure> + </example> +</section> +<!-- END examples --> + + +<!-- BEGIN processing --> +<section id="processing"> + <title>Processing Expectations</title> + + <p>Figures are displayed as block elements, with each of their child elements + being interpreted as block elements. When present, the title and description + should be displayed in a way that makes their respective roles clear.</p> +</section> +<!-- END processing --> + + +<!-- BEGIN comparison --> +<section id="comparison"> + <title>Comparison to Other Formats</title> + + <p>The <code>figure</code> is similar to the + <code href="http://www.docbook.org/tdg/en/html/figure.html">figure</code> + element in DocBook. DocBook only provides a title for figures, whereas + Mallard distinguishes between a title and a caption.</p> +</section> +<!-- END comparison --> + </page> |