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

<info>
  <link type="guide" xref="mal_info#elements"/>

  <revision version="0.1" date="2009-05-29" 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 short description of a page or section.</desc>
</info>

<title>Page Descriptions</title>

<synopsis><code mime="application/relax-ng-compact-syntax">
mal_info_desc = element desc {
  attribute * - (mal:* | local:*) { text } *,

  <link xref="mal_inline">mal_inline</link>
}
</code></synopsis>

<p>The <code>desc</code> element can be used to provide a short description
for a page or section.  While this description is generally not shown on the
page itself, it is used in automatic links to the page or section.  It may
also be used for various other purposes by different tools.</p>

<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>

  <list>
    <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 any
    <code xref="mal_info">info</code> element.</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 a block context.
    See <link xref="mal_block_desc"/> for more information.</p></item>
  </list>
</section>
<!-- END notes -->


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

  <p>The <code>desc</code> is not necessarily displayed on the page in which it
  appears.  It is, however, used for <link xref="links">automatic links</link>,
  which usually display a link block showing the title and description of the
  linked-to page or section.  When it is displayed, its contents are treated
  as inline content.</p>
</section>
<!-- END processing -->

</page>
