[mallard] Added content for block_comment, fixed some first-child issues

4 files changed, 180 insertions, 40 deletions

diff --git a/doc/mallard/C/mal_block_cite.xml b/doc/mallard/C/mal_block_cite.xml
index 2042e38..4cadc63 100644
--- a/doc/mallard/C/mal_block_cite.xml
+++ b/doc/mallard/C/mal_block_cite.xml
@@ -3,6 +3,9 @@
       id="mal_block_cite">
 
 <info>
+  <link type="seealso" xref="mal_block_comment"/>
+  <link type="seealso" xref="mal_block_quote"/>
+
   <credit type="author">
     <name>Shaun McCance</name>
     <email>shaunm@gnome.org</email>
@@ -20,9 +23,12 @@
 
 <synopsis><code mime="application/relax-ng-compact-syntax">
 mal_block_cite = element cite {
+  attribute style { xsd:NMTOKENS } ?,
+  attribute * - (mal:* | local:*) { text } *,
   attribute date { xsd:date } ?,
-  element name { <link xref="mal_inline">mal_inline</link> },
-  element email { <link xref="mal_inline">mal_inline</link> } ?
+  attribute href { text } ?,
+
+  <link xref="mal_inline">mal_inline</link>
 }
 </code></synopsis>
 
@@ -40,4 +46,24 @@ element.</p>
   <p>Add examples, processing expectations.</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>cite</code> element can have attributes from external
+    namespaces.  See <link xref="mal_attr_external"/> for more information
+    on external-namespace attributes.</p></item>
+
+    <item><p>The <code>href</code> attribute provides a URL to identify the
+    entity being cited.  It will frequently be a <sys>mailto:</sys> URL with
+    a person's email address.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
 </page>
diff --git a/doc/mallard/C/mal_block_comment.xml b/doc/mallard/C/mal_block_comment.xml
index 14c362e..2b277ec 100644
--- a/doc/mallard/C/mal_block_comment.xml
+++ b/doc/mallard/C/mal_block_comment.xml
@@ -3,19 +3,20 @@
       id="mal_block_comment">
 
 <info>
-  <link type="seealso" xref="mal_block_cite"/>
+  <version number="0.1" date="2009-05-07" status="review"/>
 
   <credit type="author">
     <name>Shaun McCance</name>
     <email>shaunm@gnome.org</email>
   </credit>
   <copyright>
-    <year>2007</year>
-    <year>2008</year>
+    <year>2007-2009</year>
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2007-02-21" status="incomplete"/>
+  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
+
+  <desc>Include an editorial comment that's hidden from normal readers.</desc>
 </info>
 
 <title>Editorial Comments</title>
@@ -27,8 +28,7 @@ mal_block_comment = element comment {
 
   <link xref="mal_title">mal_title</link> ?,
   <link xref="mal_block_cite">mal_block_cite</link>,
-  <link xref="mal_block">mal_block</link> +,
-  mal_block_comment*
+  <link xref="mal_block">mal_block</link> +
 }
 </code></synopsis>
 
@@ -40,27 +40,130 @@ elements, allowing you to have a threaded discussion inside editorial comments.<
 
 <p>A <code>comment</code> element may optionally contain a
 <code xref="mal_title">title</code> element to provide a brief description
-of the subject of the comment.  Titles are encouraged in top-level comments;
-however, they are usually unnecessary in replies.</p>
-
-<!-- FIXME
-<p>The <code xref="mal_credit">credit</code> element is a required element
-that specifies the person making the comment.  The content model for the
-<code>credit</code> element is specified in <link xref="mal_credit"/>, but
-the element is listed here explicitly to prohimit the <code>type</code>
-attribute.  Writers are highly encouraged to provide a <code xref="mal_date">mal_date</code>
-</p>
--->
+of the subject of the comment.  Titles are encouraged in top-level comments,
+although they are usually unnecessary in replies.</p>
+
+<p>The <code xref="mal_block_cite">cite</code> element is a required element
+that specifies the person making the comment.  Writers are highly encouraged
+to provide a <code>date</code> attribute.</p>
+
+
+<!-- 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>comment</code> element can have attributes from external
+    namespaces.  See <link xref="mal_attr_external"/> for more information
+    on external-namespace attributes.</p></item>
+  </list>
+</section>
+<!-- END notes -->
 
+
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Provide a comment:</p>
+
+  <example>
+    <code><![CDATA[
 <comment>
-  <title>Comment Title</title>
-  <cite date="2006-11-16"><name>Shaun McCance</name></cite>
-  <p>Add examples, processing expectations</p>
+  <title>Mallards Are Dabbling Ducks</title>
+  <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
+  <p>The information in this section is wrong.  Mallards are dabbling
+  ducks, not diving ducks.</p>
+</comment>]]></code>
+    <comment>
+      <?mal2html.show_comment?>
+      <title>Mallards Are Dabbling Ducks</title>
+      <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
+      <p>The information in this section is wrong.  Mallards are dabbling
+      ducks, not diving ducks.</p>
+    </comment>
+  </example>
+
+  <p>Use <code>comment</code> to carry out a threaded discussion:</p>
 
+  <example>
+    <code><![CDATA[
+<comment>
+  <title>Mallards Are Dabbling Ducks</title>
+  <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
+  <p>The information in this section is wrong.  Mallards are dabbling
+  ducks, not diving ducks.</p>
   <comment>
-    <cite date="2007-01-23"><name>Shaun McCance</name></cite>
-    <p>This is a test of nested comments.</p>
+    <cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite>
+    <p>But I saw a mallard dive just the other day.</p>
+    <comment>
+      <cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite>
+      <p>Rupert, please see the
+      <link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia
+      entry</link>.</p>
+    </comment>
   </comment>
-</comment>
+</comment>]]></code>
+    <comment>
+      <?mal2html.show_comment?>
+      <title>Mallards Are Dabbling Ducks</title>
+      <cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
+      <p>The information in this section is wrong.  Mallards are dabbling
+      ducks, not diving ducks.</p>
+      <comment>
+        <?mal2html.show_comment?>
+        <cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite>
+        <p>But I saw a mallard dive just the other day.</p>
+        <comment>
+          <?mal2html.show_comment?>
+          <cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite>
+          <p>Rupert, please see the
+          <link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia
+          entry</link>.</p>
+        </comment>
+      </comment>
+    </comment>
+  </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>In normal processing, <code>comment</code> elements are not displayed.
+  It may be displayed under various circumstances, such as for writing and
+  editing purposes.</p>
+
+  <p>When shown, a <code>comment</code> element is rendered as a displayed
+  block, with each of its child elements interpreted as block elements.
+  A border, background color, or other stylistic effect should be used to
+  clearly set distinguish comments from the surrounding content.</p>
+
+  <p>If a <code>title</code> element is present, it is displayed at the top
+  of the comment.  The <code>cite</code> my require special processing to
+  dispaly both its inline content and its <code>date</code> attribute.
+  Automatic text may be used for this.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+
+  <p>The <code>comment</code> element is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/remark.html">remark</code>
+  element in DocBook.  The DocBook <code>remark</code> element may be used
+  in either a block or an inline context, whereas the <code>comment</code>
+  element may only be used as a block element.  The DocBook <code>remark</code>
+  element does not provide a way to supply a title or the name of the person
+  making the remark.</p>
+</section>
+<!-- END comparison -->
 
 </page>
diff --git a/xslt/mallard/html/mal2html-block.xsl b/xslt/mallard/html/mal2html-block.xsl
index e89122e..3116d81 100644
--- a/xslt/mallard/html/mal2html-block.xsl
+++ b/xslt/mallard/html/mal2html-block.xsl
@@ -203,7 +203,8 @@ FIXME
 <!-- = comment = -->
 <xsl:template mode="mal2html.block.mode" match="mal:comment">
   <xsl:param name="first_child" select="not(preceding-sibling::*)"/>
-  <xsl:if test="$mal2html.editor_mode">
+  <xsl:if test="$mal2html.editor_mode
+                or processing-instruction('mal2html.show_comment')">
     <div>
       <xsl:attribute name="class">
         <xsl:text>comment</xsl:text>
@@ -214,7 +215,8 @@ FIXME
       <xsl:apply-templates mode="mal2html.block.mode" select="mal:title"/>
       <xsl:apply-templates mode="mal2html.block.mode" select="mal:cite"/>
       <xsl:for-each select="mal:*[not(self::mal:title or self::mal:cite)
-                            and not($mal2html.editor_mode and self::mal:comment)]">
+                            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>
@@ -227,18 +229,21 @@ FIXME
 <xsl:template mode="mal2html.block.mode" match="mal:comment/mal:cite">
   <div class="cite">
     <!-- FIXME: i18n -->
+    <xsl:text>from </xsl:text>
     <xsl:choose>
-      <xsl:when test="mal:name and @date">
-        <xsl:text>from </xsl:text>
-        <xsl:apply-templates mode="mal2html.inline.mode" select="mal:name"/>
-        <xsl:text> on </xsl:text>
-        <xsl:apply-templates mode="mal2html.inline.mode" select="@date"/>
+      <xsl:when test="@href">
+        <a href="{@href}">
+          <xsl:apply-templates mode="mal2html.inline.mode"/>
+        </a>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:text>from </xsl:text>
-        <xsl:apply-templates mode="mal2html.inline.mode" select="mal:name"/>
+        <xsl:apply-templates mode="mal2html.inline.mode"/>
       </xsl:otherwise>
     </xsl:choose>
+    <xsl:if test="@date">
+      <xsl:text> on </xsl:text>
+      <xsl:value-of select="@date"/>
+    </xsl:if>
   </div>
 </xsl:template>
 
@@ -252,7 +257,8 @@ FIXME
         <xsl:text> first-child</xsl:text>
       </xsl:if>
     </xsl:attribute>
-    <xsl:for-each select="mal:*[not($mal2html.editor_mode and self::mal:comment)]">
+    <xsl:for-each select="mal:*[$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>
@@ -273,7 +279,8 @@ FIXME
     <xsl:apply-templates mode="mal2html.block.mode" select="mal:title"/>
     <div class="figure-contents">
       <xsl:for-each select="mal:*[not(self::mal:title or self::mal:desc)
-                            and not($mal2html.editor_mode and self::mal:comment)]">
+                            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>
@@ -297,7 +304,8 @@ FIXME
     <xsl:apply-templates mode="mal2html.block.mode" select="mal:desc"/>
     <div class="listing-contents">
       <xsl:for-each select="mal:*[not(self::mal:title or self::mal:desc)
-                            and not($mal2html.editor_mode and self::mal:comment)]">
+                            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>
@@ -345,7 +353,8 @@ FIXME
     <xsl:apply-templates mode="mal2html.block.mode" select="mal:desc"/>
     <div class="synopsis-contents">
       <xsl:for-each select="mal:*[not(self::mal:title or self::mal:desc)
-                            and not($mal2html.editor_mode and self::mal:comment)]">
+                            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>
diff --git a/xslt/mallard/html/mal2html-page.xsl b/xslt/mallard/html/mal2html-page.xsl
index c4ac9f1..81c6430 100644
--- a/xslt/mallard/html/mal2html-page.xsl
+++ b/xslt/mallard/html/mal2html-page.xsl
@@ -432,7 +432,8 @@ REMARK: Describe this template
   <div class="contents">
     <xsl:for-each
         select="mal:*[not(self::mal:section or self::mal:title or self::mal:subtitle)
-                and not($mal2html.editor_mode and self::mal:comment)]">
+                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>
@@ -457,7 +458,8 @@ REMARK: Describe this template
     <div class="contents">
       <xsl:for-each
           select="mal:*[not(self::mal:section or self::mal:title or self::mal:subtitle)
-                  and not($mal2html.editor_mode and self::mal:comment)]">
+                  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>