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

<info>
  <revision version="0.1" date="2009-05-28" 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>Break up pages into logical chunks to help readers find
  information quickly.</desc>
</info>

<title>Sections</title>

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

  <link xref="mal_info">mal_info</link> ?,
  <link xref="mal_block_title">mal_block_title</link>,
  <link xref="mal_block">mal_block</link> *,
  mal_section *
}
</code></synopsis>

<p>A section is a prominent logical part of a page or another section.
Breaking up material into sections can help readers find information
more quickly.  In Mallard, sections can take part in
<link xref="links">automatic linking</link> just as pages can.</p>

<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>section</code> element contains an optional
    <code xref="mal_info">info</code> element, a <code xref="mal_block_title">title</code>
    element, any <link xref="mal_block">general block content</link>, and
    any number of <code xref="mal_section">section</code> elements.</p></item>

    <item><p>The <code>section</code> can occur in <code xref="mal_page">page</code>
    elements and other <code>section</code> elements.</p></item>

    <item><p>The <code>id</code> attribute takes a unique identifier.  It should
    be distinct from all other <code>id</code> attributes in the same page,
    including those on other <code>section</code> elements and on the containing
    <code xref="mal_page">page</code> element.</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>section</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 processing -->
<section id="processing">
  <title>Processing Expectations</title>

  <p>Each section is displayed as a block.  The title of a section is displayed
  prominently, followed by any child block content, and finally by each child
  section.  Note that automatic links, style hints, or other special features
  may insert material or change the way pages are displayed.  Sections should
  be clearly separated from their surrounding content to make the beginning and
  ending of each section obvious.  The depth of each section should be clear,
  although this may not be feasible for deeply nested sections.</p>

  <p>Sections may have links associated with them.  All sections should have
  guide links and see also links displayed when applicable.  See
  <link xref="links#guide"/> and <link xref="links#seealso"/> for more
  information.  Sections in guide pages have topic links inserted following
  their block content.  See <link xref="links#topic"/> for more information.</p>
</section>
<!-- END processing -->

</page>
