[gnome-doc-utils/mallard] [mallard] Added information and xslt for synopsis and listing

[Shaun McCance <shaunm src gnome org>]

commit bca325a88952f22bd8d7c4b15cd13fd3b91f5490
Author: Shaun McCance <shaunm gnome org>
Date:   Sun May 3 15:21:45 2009 -0500

    [mallard] Added information and xslt for synopsis and listing
---
 doc/mallard/C/mal_block_synopsis.xml |   71 ++++++++++++++++++++++++++++++++--
 xslt/mallard/html/mal2html-block.xsl |   33 ++++++++--------
 xslt/mallard/html/mal2html-page.xsl  |    2 +-
 3 files changed, 85 insertions(+), 21 deletions(-)

diff --git a/doc/mallard/C/mal_block_synopsis.xml b/doc/mallard/C/mal_block_synopsis.xml
index cbc7749..9e176eb 100644
--- a/doc/mallard/C/mal_block_synopsis.xml
+++ b/doc/mallard/C/mal_block_synopsis.xml
@@ -3,8 +3,22 @@
       id="mal_block_synopsis">
 
 <info>
-  <link type="guide" xref="mal_block#containers"/>
+  <link type="guide" xref="mal_block#elements"/>
+
   <version number="0.1" date="2007-02-21" status="incomplete"/>
+
+  <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 an overview of concepts.</desc>
 </info>
 
 <title>Synopses</title>
@@ -15,6 +29,7 @@ mal_block_synopsis = element synopsis {
   attribute * - (mal:* | local:*) { text } *,
 
   <link xref="mal_title">mal_title</link> ?,
+  <link xref="mal_block_desc">mal_block_desc</link> ?,
   <link xref="mal_block">mal_block</link> +
 }
 </code></synopsis>
@@ -30,19 +45,67 @@ control element.</p>
   <p>Add explanation, examples</p>
 </comment>
 
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <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>synopsis</code> element can have attributes from external
+    namespaces.  See <link xref="mal_attr_external"/> for more information
+    on external-namespace attributes on inline elements.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Use <code>synopsis</code> to create an overview of functions:</p>
+
+  <example>
+    <code><![CDATA[<synopsis>
+<title>Beanstalk Functions</title>
+<desc>Use these methods on a <code>Beanstalk</code> object.</desc>
+<code>
+void add_bean    (Bean bean);
+int  count_beans ();
+</code>
+</synopsis>
+]]></code>
+    <synopsis>
+      <title>Beanstalk Functions</title>
+      <desc>Use these methods on a <code>beanstalk</code> object.</desc>
+      <code>
+void add_bean    (Bean bean);
+int  count_beans ();
+</code>
+    </synopsis>
+  </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
 
   <p>A <code>synopsis</code> element is rendered as a displayed block,
   with each of its child elements interpreted as block elements.  Since
   a <code>synopsis</code> element often contains large blocks, and is
-  generally offset from the running text, display tools may opt to
-  render it inside a colored or screened box, with a border, or
-  otherwise differently from the surrounding text.</p>
+  generally offset from the running text, display tools may opt to render
+  it inside a colored box, with a border, or otherwise differently from
+  the surrounding text.</p>
 
   <p>If a <code xref="mal_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>
 </section>
+<!-- END processing -->
 
 </page>
diff --git a/xslt/mallard/html/mal2html-block.xsl b/xslt/mallard/html/mal2html-block.xsl
index fb3fad2..287faa3 100644
--- a/xslt/mallard/html/mal2html-block.xsl
+++ b/xslt/mallard/html/mal2html-block.xsl
@@ -37,16 +37,17 @@ REMARK: Describe this template
 <xsl:template name="mal2html.block.css">
 <xsl:text>
 div.title {
-  font-size: 1.2em;
-  margin-top: 0;
+  margin: 0 0 0.2em 0;
   font-weight: bold;
   color: </xsl:text>
   <xsl:call-template name="theme.get_color">
     <xsl:with-param name="id" select="'text-light'"/>
   </xsl:call-template>
   <xsl:text>;
-  font-weight: bold;
 }
+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;
@@ -66,6 +67,8 @@ div.example {
   padding-left: 1em;
 }
 div.figure {
+  margin-left: 1.72em;
+  padding: 4px;
   color: </xsl:text>
   <xsl:call-template name="theme.get_color">
     <xsl:with-param name="id" select="'text-light'"/>
@@ -81,10 +84,11 @@ div.figure {
     <xsl:with-param name="id" select="'gray-background'"/>
   </xsl:call-template>
   <xsl:text>;
-  margin-left: 1.72em;
-  padding: 4px;
 }
 div.figure-contents {
+  margin: 0;
+  padding: 0.5em 1em 0.5em 1em;
+  text-align: center;
   color: </xsl:text>
   <xsl:call-template name="theme.get_color">
     <xsl:with-param name="id" select="'text'"/>
@@ -100,15 +104,12 @@ div.figure-contents {
     <xsl:with-param name="id" select="'background'"/>
   </xsl:call-template>
   <xsl:text>;
-  padding: 0.5em 1em 0.5em 1em;
+}
+div.listing-contents {
   margin: 0;
-  text-align: center;
 }
-div.figure div.title { margin: 0 0 4px 0; }
-div.figure div.desc { margin: 4px 0 0 0; }
-div.listing div.title { font-size: 1em; margin: 0 0 4px 0; }
-div.listing div.desc { margin: 0 0 4px 0; font-style: italic; }
 pre.screen {
+  padding: 0.5em 1em 0.5em 1em;
   background-color: </xsl:text>
   <xsl:call-template name="theme.get_color">
     <xsl:with-param name="id" select="'gray-background'"/>
@@ -119,9 +120,10 @@ pre.screen {
     <xsl:with-param name="id" select="'gray-border'"/>
   </xsl:call-template>
   <xsl:text>;
-  padding: 0.5em 1em 0.5em 1em;
 }
-div.synopsis {
+div.synopsis-contents {
+  margin: 0;
+  padding: 0.5em 1em 0.5em 1em;
   border-top: solid 2px;
   border-bottom: solid 2px;
   border-color: </xsl:text>
@@ -134,7 +136,6 @@ div.synopsis {
     <xsl:with-param name="id" select="'gray-background'"/>
   </xsl:call-template>
   <xsl:text>;
-  padding: 0.5em 1em 0.5em 1em;
 }
 div.synopsis pre.code {
   background: none;
@@ -186,7 +187,7 @@ FIXME
 
 <!-- = desc = -->
 <xsl:template mode="mal2html.block.mode" match="mal:desc">
-  <div class="desc">
+  <div class="desc desc-{local-name(..)}">
     <xsl:apply-templates mode="mal2html.inline.mode"/>
   </div>
 </xsl:template>
@@ -348,7 +349,7 @@ FIXME
 </xsl:template>
 
 <xsl:template mode="mal2html.block.mode" match="mal:title">
-  <div class="title">
+  <div class="title title-{local-name(..)}">
     <xsl:apply-templates mode="mal2html.inline.mode"/>
   </div>
 </xsl:template>
diff --git a/xslt/mallard/html/mal2html-page.xsl b/xslt/mallard/html/mal2html-page.xsl
index 2e2d6d0..ee56999 100644
--- a/xslt/mallard/html/mal2html-page.xsl
+++ b/xslt/mallard/html/mal2html-page.xsl
@@ -426,7 +426,7 @@ REMARK: Describe this template
 <!-- = page = -->
 <xsl:template match="mal:page">
   <div class="header">
-    <xsl:apply-templates mode="mal2html.block.mode"
+    <xsl:apply-templates mode="mal2html.title.mode"
                          select="mal:title | mal:subtitle"/>
   </div>
   <div class="contents">