[mallard] Work on block_quote and block_synopsis

5 files changed, 233 insertions, 18 deletions

diff --git a/doc/mallard/C/mal_block_quote.xml b/doc/mallard/C/mal_block_quote.xml
index 8cee8d8..53dd3c7 100644
--- a/doc/mallard/C/mal_block_quote.xml
+++ b/doc/mallard/C/mal_block_quote.xml
@@ -1,34 +1,52 @@
 <page xmlns="http://www.gnome.org/~shaunm/mallard"
-      type="topic" id="mal_block_quote">
+      type="topic"
+      id="mal_block_quote">
 
 <info>
   <link type="seealso" xref="mal_inline_quote"/>
-  <version number="0.1" date="2007-02-21" status="stub"/>
+
+  <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>Create a block-level quotation with an attribution.</desc>
 </info>
 
-<title>Quotes</title>
+<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>
 
-<comment>
-  <cite date="2007-02-21"><name>Shaun McCance</name></cite>
-  <p>render quotes around inline</p>
-  <p>style="epipgraph"</p>
-</comment>
+<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 type="bullet">
     <item><p>The <code>quote</code> element contains an optional
-    <link xref="mal_block_title">title</link> element, a
-    <link xref="mal_block_cite">cite</link> element, and  any
+    <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
@@ -40,6 +58,17 @@ mal_block_quote = element quote {
     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>
@@ -50,4 +79,83 @@ mal_block_quote = element quote {
 </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>
diff --git a/doc/mallard/C/mal_block_synopsis.xml b/doc/mallard/C/mal_block_synopsis.xml
index 07a207f..3541412 100644
--- a/doc/mallard/C/mal_block_synopsis.xml
+++ b/doc/mallard/C/mal_block_synopsis.xml
@@ -3,7 +3,9 @@
       id="mal_block_synopsis">
 
 <info>
-  <version number="0.1" date="2007-02-21" status="incomplete"/>
+  <link type="seealso" xref="mal_block_listing"/>
+
+  <version number="0.1" date="2009-05-19" status="review"/>
 
   <credit type="author">
     <name>Shaun McCance</name>
@@ -110,10 +112,25 @@ int  count_beans ();
   it inside a colored box, with a border, or otherwise differently from
   the surrounding text.</p>
 
-  <p>If a <code xref="mal_block_title">title</code> element is provided, it
-  should appear at the top of the block and be clearly marked as the
-  title using font variations or other stylistic means.</p>
+  <p>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>synopsis</code> element is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/synopsis.html">synopsis</code>
+  element in DocBook, although the DocBook element is not a formal element.
+  DocBook also provides the
+  <code href="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</code> and
+  <code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html">funcsynopsis</code>
+  elements, which attempt to model the data for command and function synopses,
+  respectively.  Mallard does not provide modelling elements.</p>
+</section>
+<!-- END comparison -->
+
 </page>
diff --git a/sandbox/mallard/html/Makefile b/sandbox/mallard/html/Makefile
index 6c2596f..f7cbe6d 100644
--- a/sandbox/mallard/html/Makefile
+++ b/sandbox/mallard/html/Makefile
@@ -2,8 +2,9 @@ xslts=$(wildcard ../../../xslt/mallard/common/*.xsl) $(wildcard ../../../xslt/ma
 specs=$(filter-out ../../../doc/mallard/C/legal.xml, $(wildcard ../../../doc/mallard/C/*.xml))
 pages=$(patsubst %.xml,%.html, $(notdir $(specs)))
 icons=admon-bug.png admon-caution.png admon-important.png admon-note.png admon-tip.png admon-warning.png
+marks=watermark-blockquote-201C.png watermark-code.png
 
-all: $(pages) $(icons) figures mallard.cache
+all: $(pages) $(icons) $(marks) figures mallard.cache
 
 mallard.cache : $(specs) $(xslts)
 	echo '<cache xmlns="http://www.gnome.org/~shaunm/mallard">' > $@.in
@@ -17,6 +18,8 @@ mallard.cache : $(specs) $(xslts)
 
 $(icons):
 	ln -sf ../../../data/icons/hicolor/24x24/$@ $@
+$(marks):
+	ln -sf ../../../data/watermarks/$@ $@
 
 $(pages) : mallard.cache $(xslts)
 $(pages) : %.html : ../../../doc/mallard/C/%.xml
diff --git a/xslt/common/theme.xsl b/xslt/common/theme.xsl
index c078c76..ac21fa5 100644
--- a/xslt/common/theme.xsl
+++ b/xslt/common/theme.xsl
@@ -255,4 +255,15 @@ document is written in.
   </xsl:call-template>
 </xsl:param>
 
+<!--@@==========================================================================
+theme.watermark.code
+The path for the code block watermark graphic
+
+This parameter specifies the graphic file used for code block watermarks.
+-->
+<xsl:param name="theme.watermark.code">
+  <xsl:value-of select="$theme.watermark.path"/>
+  <xsl:text>watermark-code.png</xsl:text>
+</xsl:param>
+
 </xsl:stylesheet>
diff --git a/xslt/mallard/html/mal2html-block.xsl b/xslt/mallard/html/mal2html-block.xsl
index 8a1260d..e64825f 100644
--- a/xslt/mallard/html/mal2html-block.xsl
+++ b/xslt/mallard/html/mal2html-block.xsl
@@ -46,8 +46,8 @@ div.desc { margin: 0 0 0.2em 0; }
 div.desc-listing, div.desc-synopsis { font-style: italic; }
 div.desc-figure { margin: 0.2em 0 0 0; }
 pre.code {
-  <!-- FIXME: theme -->
-  background: url(mallard-icon-code.png) no-repeat top right;
+  background: url('</xsl:text>
+    <xsl:value-of select="$theme.watermark.code"/><xsl:text>') no-repeat top right;
   border: solid 2px </xsl:text>
     <xsl:value-of select="$theme.color.gray_border"/><xsl:text>;
   padding: 0.5em 1em 0.5em 1em;
@@ -109,6 +109,34 @@ div.note-tip div.note-inner { background-image: url("</xsl:text>
 div.note-warning div.note-inner { background-image: url("</xsl:text>
   <xsl:value-of select="$theme.icon.admon.warning"/><xsl:text>"); }
 div.note-contents { margin: 0; padding: 0; }
+div.quote-inner {
+  margin: 0;
+  <!-- FIXME: i18n -->
+  background-image: url('</xsl:text>
+    <xsl:value-of select="$theme.watermark.blockquote"/><xsl:text>');
+  background-repeat: no-repeat;
+  background-position: top left;
+  padding: 0.5em;
+  padding-left: 4em;
+}
+div.title-quote {
+  margin-left: 4em;
+}
+blockquote {
+  margin: 0; padding: 0;
+}
+div.cite-comment {
+  margin-top: 0.5em;
+  color: </xsl:text><xsl:value-of select="$theme.color.text_light"/><xsl:text>;
+}
+div.cite-quote {
+  margin-top: 0.5em;
+  color: </xsl:text><xsl:value-of select="$theme.color.text_light"/><xsl:text>;
+}
+div.cite-quote::before {
+  <!-- FIXME: i18n -->
+  content: '&#x2015; ';
+}
 pre.screen {
   padding: 0.5em 1em 0.5em 1em;
   background-color: </xsl:text>
@@ -216,7 +244,7 @@ FIXME
 
 <!-- = comment/cite = -->
 <xsl:template mode="mal2html.block.mode" match="mal:comment/mal:cite">
-  <div class="cite">
+  <div class="cite cite-comment">
     <!-- FIXME: i18n -->
     <xsl:text>from </xsl:text>
     <xsl:choose>
@@ -367,6 +395,54 @@ FIXME
   </p>
 </xsl:template>
 
+<!-- = quote = -->
+<xsl:template mode="mal2html.block.mode" match="mal:quote">
+  <xsl:param name="first_child" select="not(preceding-sibling::*)"/>
+  <div class="quote">
+    <xsl:attribute name="class">
+      <xsl:text>quote</xsl:text>
+      <xsl:if test="$first_child">
+        <xsl:text> first-child</xsl:text>
+      </xsl:if>
+    </xsl:attribute>
+    <xsl:apply-templates mode="mal2html.block.mode" select="mal:title"/>
+    <div class="quote-inner">
+      <blockquote class="quote-contents">
+        <xsl:for-each select="mal:*[not(self::mal:title or self::mal:cite)
+                              and ($mal2html.editor_mode or not(self::mal:comment)
+                              or processing-instruction('mal2html.show_comment'))]">
+          <xsl:apply-templates mode="mal2html.block.mode" select=".">
+            <xsl:with-param name="first_child" select="position() = 1"/>
+          </xsl:apply-templates>
+        </xsl:for-each>
+      </blockquote>
+      <xsl:apply-templates mode="mal2html.block.mode" select="mal:cite"/>
+    </div>
+  </div>
+</xsl:template>
+
+<!-- = quote/cite = -->
+<xsl:template mode="mal2html.block.mode" match="mal:quote/mal:cite">
+  <div class="cite cite-quote">
+    <xsl:choose>
+      <xsl:when test="@href">
+        <a href="{@href}">
+          <xsl:apply-templates mode="mal2html.inline.mode"/>
+        </a>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:apply-templates mode="mal2html.inline.mode"/>
+      </xsl:otherwise>
+    </xsl:choose>
+    <!-- FIXME: i18n -->
+    <xsl:if test="@date">
+      <xsl:text> (</xsl:text>
+      <xsl:value-of select="@date"/>
+      <xsl:text>)</xsl:text>
+    </xsl:if>
+  </div>
+</xsl:template>
+
 <!-- = screen = -->
 <xsl:template mode="mal2html.block.mode" match="mal:screen">
   <xsl:param name="first_child" select="not(preceding-sibling::*)"/>