<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="mal_block_listing">

<info>
  <link type="seealso" xref="mal_block_code"/>
  <link type="seealso" xref="mal_block_figure"/>

  <revision version="0.1" date="2009-05-19" status="review"/>

  <credit type="author">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
    <years>2008-2009</years>
  </credit>

  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <desc>Provide a name and description for a code block or other content.</desc>
</info>

<title>Listings</title>

<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_listing = element listing {
  attribute style { xsd:NMTOKENS } ?,
  attribute * - (mal:* | local:*) { text } *,

  <link xref="mal_block_title">mal_block_title</link> ?,
  <link xref="mal_block_desc">mal_block_desc</link> ?,
  <link xref="mal_block">mal_block</link> +
}
</code></synopsis>

<p>Use the <code>listing</code> element to create named listing of file contents
or other content.  Listings are usually used with <link xref="mal_block_code">code
blocks</link> to provide a name for the file to enter the content into.  They may
also be used to provide a name for an <link xref="mal_block_screen">interactive
shell session</link> or any other type of content.  To provide a title for images
or other multimedia objects, use the <link xref="mal_block_figure">figure</link>
element.</p>

<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>listing</code> element contains an optional
    <link xref="mal_block_title">title</link> element, an optional
    <link xref="mal_block_desc">desc</link> element, and  any
    <link xref="mal_block">general block content</link>.</p></item>

    <item><p>The <code>listing</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>listing</code> element can have attributes from external
    namespaces.  See <link xref="mal_external"/> for more information
    on external-namespace attributes.</p></item>
  </list>
</section>
<!-- END notes -->


<!-- BEGIN examples -->
<section id="examples">
  <title>Examples</title>

  <p>Use <code>listing</code> to provide a file name and description for a
  code block:</p>

  <example>
    <code><![CDATA[
<listing>
  <title><file>index.page</file></title>
  <desc>A first Mallard page</desc>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
  <!-- Content goes here -->
</page>]]]>]><![CDATA[</code>
</listing>]]></code>
    <listing>
      <title><file>index.page</file></title>
      <desc>A first Mallard page</desc>
      <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
  <!-- Content goes here -->
</page>]]></code>
    </listing>
  </example>
</section>
<!-- END examples -->


<!-- BEGIN processing -->
<section id="processing">
  <title>Processing Expectations</title>

  <p>Listings 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 -->
<!--
No direct analog in DocBook.  I'm sure people accomplish the same thing somehow,
but my brain isn't working right now.  Also check DITA.
<section id="comparison">
  <title>Comparison to Other Formats</title>
</section>
-->
<!-- END comparison -->

</page>
