diff options
author | Shaun McCance <shaunm@gnome.org> | 2009-05-23 16:04:06 -0500 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2009-05-23 16:04:06 -0500 |
commit | b24a1092e4537d9cd705063fd8627bb84f3fb483 (patch) | |
tree | cb3d6222585f50fa625d2fa8fb92e24f8c0eef71 | |
parent | d2a7927e961d2649e806538237cc06d62fed7aa3 (diff) | |
download | yelp-tools-b24a1092e4537d9cd705063fd8627bb84f3fb483.tar.gz |
[mallard] Finished off block_steps and xslt implementation of mal:steps
-rw-r--r-- | doc/mallard/C/mal_block_steps.xml | 120 | ||||
-rw-r--r-- | 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::*)"/> |