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

<info>
  <revision version="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>Create a block-level quotation with an attribution.</desc>
</info>

<title>Block Quotes</title>

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

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

<p>The <code>quote</code> element allows you to mark a quoted block of text
and include an attribution for the quote.  Block quotations are useful for
long passages, or for quotes you want to draw attention to.  You can provide
an attribution using the <code xref="mal_block_cite">cite</code> element,
and have it automatically formatted by display tools.</p>

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

    <item><p>The <code>quote</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 following style hints are recommended:</p>
      <table rules="rows">
        <tr>
          <td><p><code>epigraph</code></p></td>
          <td><p>an introductory or closing quote that is not part of the
          running prose, generally formatted flush right</p></td>
        </tr>
      </table>
    </item>

    <item><p>The <code>quote</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>Include a simple block quote in your document:</p>

  <example>
    <code><![CDATA[
<quote>
  <cite>Henry David Thoreau</cite>
  <p>Our life is frittered away by detail.... Simplify, simplify.</p>
</quote>
]]></code>
    <quote>
      <cite>Henry David Thoreau</cite>
      <p>Our life is frittered away by detail.... Simplify, simplify.</p>
    </quote>
  </example>

  <p>Add a title to the quote:</p>

  <example>
    <code><![CDATA[
<quote>
  <title>Simplify</title>
  <cite>Henry David Thoreau</cite>
  <p>Our life is frittered away by detail.... Simplify, simplify.</p>
</quote>
]]></code>
    <quote>
      <title>Simplify</title>
      <cite>Henry David Thoreau</cite>
      <p>Our life is frittered away by detail.... Simplify, simplify.</p>
    </quote>
  </example>

  <p>Add a date to the attribution:</p>

  <example>
    <code><![CDATA[
<quote>
  <cite date="1854">Henry David Thoreau</cite>
  <p>Our life is frittered away by detail.... Simplify, simplify.</p>
</quote>
]]></code>
    <quote>
      <cite date="1854">Henry David Thoreau</cite>
      <p>Our life is frittered away by detail.... Simplify, simplify.</p>
    </quote>
  </example>
</section>
<!-- END examples -->


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

  <p>Block quotes are displayed as block elements, with each of their child
  elements being interpreted as block elements.  When present, the title and
  attribution should be displayed in a way that makes their respective roles
  clear.  Block quotes are frequently adorned with a watermark of quotation
  marks.  Processing tools should ensure any quotation marks used in the
  formatting of quotes, including watermark images, are appropriate for the
  document's language.</p>
</section>
<!-- END processing -->


<!-- BEGIN comparison -->
<section id="comparison">
  <title>Comparison to Other Formats</title>
  <p>The <code>quote</code> element is similar to the
  <code href="http://www.docbook.org/tdg/en/html/blockquote.html">blockquote</code>
  element in DocBook.  The <code xref="mal_block_cite">cite</code> element is
  mandatory in Mallard, whereas attribution is optional in DocBook.</p>
</section>
<!-- END comparison -->
</page>
