[gnome-doc-utils/mallard] [mallard] Finished off block_steps and xslt implementation of mal:steps

[Shaun McCance <shaunm src gnome org>]

commit b24a1092e4537d9cd705063fd8627bb84f3fb483
Author: Shaun McCance <shaunm gnome org>
Date:   Sat May 23 16:04:06 2009 -0500

    [mallard] Finished off block_steps and xslt implementation of mal:steps
---
 doc/mallard/C/mal_block_steps.xml   |  120 ++++++++++++++++++++++++++++++++---
 xslt/mallard/html/mal2html-list.xsl |   57 +++++++++++++++++
 2 files changed, 169 insertions(+), 8 deletions(-)

diff --git a/doc/mallard/C/mal_block_steps.xml b/doc/mallard/C/mal_block_steps.xml
index 1e18daa..a5dc217 100644
--- a/doc/mallard/C/mal_block_steps.xml
+++ b/doc/mallard/C/mal_block_steps.xml
@@ -3,7 +3,7 @@
       id="mal_block_steps">
 
 <info>
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <version number="0.1" date="2009-05-23" status="review"/>
 
   <credit type="author">
     <name>Shaun McCance</name>
@@ -15,6 +15,8 @@
   </copyright>
 
   <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+  <desc>Create a list of steps the reader should perform to accomplish a task.</desc>
 </info>
 
 <title>Procedures</title>
@@ -35,21 +37,24 @@ mal_block_steps = element steps {
 }
 </code></synopsis>
 
-<comment>
-<cite date="2009-05-20">shaunm</cite>
-<p>add intro text</p>
-</comment>
+<p>Use the <code>steps</code> element to create a list of steps the reader
+should follow.  The <code>steps</code> element is structurally similar to
+the <code xref="mal_block_list">list</code> element, but marking the list
+as being instructions to the reader allows special display rules to be
+applied.  If you want a numbered list that is not a procedure, use the
+<code xref="mal_block_list">list</code> element with the <code>type</code>
+attribute to <code>"numbered"</code> instead.</p>
 
 <!-- BEGIN notes -->
 <section id="notes">
   <title>Notes</title>
   <list>
-    <item><p>The <code>olist</code> element can contain an optional
+    <item><p>The <code>steps</code> element can contain an optional
     <code xref="mal_block_title">title</code> element followed by one or more
     <code>item</code> elements.  Each child <code>item</code> element contains
     any <link xref="mal_inline">general inline elements</link>.</p></item>
 
-    <item><p>The <code>olist</code> element can occur in any
+    <item><p>The <code>steps</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>
@@ -58,7 +63,7 @@ mal_block_steps = element steps {
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
 
-    <item><p>The <code>olist</code> element can have attributes from external
+    <item><p>The <code>steps</code> element can have attributes from external
     namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
@@ -69,6 +74,72 @@ mal_block_steps = element steps {
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
+
+  <p>Create a simple procedure of steps for the reader to follow:</p>
+
+  <example>
+    <code><![CDATA[
+<steps>
+  <title>Planting Magic Beans</title>
+  <item><p>Dig a hole 10cm deep.</p></item>
+  <item><p>Place magic beans in the hole.</p></item>
+  <item><p>Fill hole with fertilized soil.</p></item>
+  <item><p>Water frequently.</p></item>
+</steps>
+]]></code>
+    <steps>
+      <title>Planting Magic Beans</title>
+      <item><p>Dig a hole 10cm deep.</p></item>
+      <item><p>Place magic beans in the hole.</p></item>
+      <item><p>Fill hole with fertilized soil.</p></item>
+      <item><p>Water frequently.</p></item>
+    </steps>
+  </example>
+
+  <p>Create a procedure with a nested list and a nested procedure:</p>
+
+  <example>
+    <code><![CDATA[
+<steps>
+  <title>Planting Magic Beans</title>
+  <item>
+    <p>Perform one of the following:</p>
+    <list>
+      <item><p>Dig a whole 10cm deep.</p></item>
+      <item><p>Find a whole 10cm deep.</p></item>
+    </list>
+  </item>
+  <item><p>Place magic beans in the hole.</p></item>
+  <item><p>Fill hole with fertilized soil.</p></item>
+  <item>
+    <p>Water frequently with the following steps:</p>
+    <steps>
+      <item><p>Fill watering can with water.</p></item>
+      <item><p>Pour water onto spot where beans were planted.</p></item>
+    </steps>
+  </item>
+</steps>
+]]></code>
+    <steps>
+      <title>Planting Magic Beans</title>
+      <item>
+        <p>Perform one of the following:</p>
+        <list>
+          <item><p>Dig a whole 10cm deep.</p></item>
+          <item><p>Find a whole 10cm deep.</p></item>
+        </list>
+      </item>
+      <item><p>Place magic beans in the hole.</p></item>
+      <item><p>Fill hole with fertilized soil.</p></item>
+      <item>
+        <p>Water frequently with the following steps:</p>
+        <steps>
+          <item><p>Fill watering can with water.</p></item>
+          <item><p>Pour water onto spot where beans were planted.</p></item>
+        </steps>
+      </item>
+    </steps>
+  </example>
 </section>
 <!-- END examples -->
 
@@ -77,6 +148,15 @@ mal_block_steps = element steps {
 <section id="processing">
   <title>Processing Expectations</title>
 
+  <p>Procedures are displayed as block elements, with each child <code>item</code>
+  displayed as a numbered list item.  When present, the <code>title</code> element
+  should be displayed in a way that makes it clear that it is the title of the list.
+  List items are interpreted in the same way as <code>li</code> elements in HTML,
+  except that the <code>item</code> element only allows block-level child content.</p>
+
+  <p>Procedures should have a background color, border, or other styling effect
+  to clearly differentiate them from basic numbered lists.  Special styling allows
+  readers to skim pages more easily.</p>
 </section>
 <!-- END processing -->
 
@@ -84,6 +164,30 @@ mal_block_steps = element steps {
 <!-- BEGIN comparison -->
 <section id="comparison">
   <title>Comparison to Other Formats</title>
+
+  <p>The <code>steps</code> element is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/procedure.html";>procedure</code>
+  element in DocBook.  Note the following differences:</p>
+
+  <list>
+    <item><p>Instead of a separate
+    <code href="http://www.docbook.org/tdg/en/html/step.html";>step</code> element,
+    Mallard simply uses the common <code>item</code> element for each step.</p></item>
+
+    <item><p>DocBook provides an explicit
+    <code href="http://www.docbook.org/tdg/en/html/substeps.html";>substeps</code>
+    element.  Mallard provides no such element; simply nest <code>steps</code>
+    elements for the same effect.</p></item>
+
+    <item><p>Mallard provides no equivalent to the
+    <code href="http://www.docbook.org/tdg/en/html/stepalternatives.html";>stepalternatives</code>
+    element.  Use a <code xref="mal_block_list">basic bulleted list</code> with
+    introductory text when this is needed.</p></item>
+
+    <item><p>DocBook allows leading block-level content in the <code>procedure</code>
+    element.  This is not allowed in Mallard, though an optional <code>title</code>
+    element is allowed.</p></item>
+  </list>
 </section>
 <!-- END comparison -->
 
diff --git a/xslt/mallard/html/mal2html-list.xsl b/xslt/mallard/html/mal2html-list.xsl
index ebd3312..0871091 100644
--- a/xslt/mallard/html/mal2html-list.xsl
+++ b/xslt/mallard/html/mal2html-list.xsl
@@ -36,9 +36,28 @@ REMARK: Describe this template
 -->
 <xsl:template name="mal2html.list.css">
 <xsl:text>
+div.title-list { margin-bottom: 0.5em; }
 ol.list, ul.list { margin: 0; padding: 0; }
 li.item-list { margin-left: 1.44em; }
 
+div.steps {
+  padding: 0.5em 1em 0.5em 1em;
+  border-top: solid 2px;
+  border-bottom: solid 2px;
+  border-color: </xsl:text>
+    <xsl:value-of select="$theme.color.blue_border"/><xsl:text>;
+  background-color: </xsl:text>
+    <xsl:value-of select="$theme.color.yellow_background"/><xsl:text>;
+}
+div.steps div.steps {
+  padding: 0;
+  border: none;
+  background-color: none;
+}
+div.title-steps { margin-bottom: 0.5em; }
+ol.steps, ul.steps { margin: 0; padding: 0; }
+li.item-steps { margin-left: 1.44em; }
+
 ul.tree {
   margin: 0; padding: 0;
   list-style-type: none;
@@ -80,6 +99,7 @@ div.tree-lines ul.tree ul.tree ul.tree {
         <xsl:text> first-child</xsl:text>
       </xsl:if>
     </xsl:attribute>
+    <xsl:apply-templates mode="mal2html.block.mode" select="mal:title"/>
     <xsl:element name="{$el}" namespace="{$mal2html.namespace}">
       <xsl:attribute name="class">
         <xsl:text>list</xsl:text>
@@ -114,6 +134,43 @@ div.tree-lines ul.tree ul.tree ul.tree {
   </li>
 </xsl:template>
 
+<!-- = steps = -->
+<xsl:template mode="mal2html.block.mode" match="mal:steps">
+  <xsl:param name="first_child" select="not(preceding-sibling::*)"/>
+  <div>
+    <xsl:attribute name="class">
+      <xsl:text>steps</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"/>
+    <ol class="steps">
+      <xsl:apply-templates mode="mal2html.list.steps.mode" select="mal:item"/>
+    </ol>
+  </div>
+</xsl:template>
+
+<!-- = list/item = -->
+<xsl:template mode="mal2html.list.steps.mode" match="mal:item">
+  <li>
+    <xsl:attribute name="class">
+      <xsl:text>item-steps</xsl:text>
+      <xsl:if test="not(preceding-sibling::mal:item)">
+        <xsl:text> first-child</xsl:text>
+      </xsl:if>
+    </xsl:attribute>
+    <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>
+    </xsl:for-each>
+  </li>
+</xsl:template>
+
 <!-- = tree = -->
 <xsl:template mode="mal2html.block.mode" match="mal:tree">
   <xsl:param name="first_child" select="not(preceding-sibling::*)"/>