[gnome-doc-utils/mallard] [mallard] Finished off block_note
- From: Shaun McCance <shaunm src gnome org>
- To: svn-commits-list gnome org
- Subject: [gnome-doc-utils/mallard] [mallard] Finished off block_note
- Date: Mon, 18 May 2009 21:53:23 -0400 (EDT)
commit 31d0d5157a0f2a3328a9c9f061a95830124efc0f
Author: Shaun McCance <shaunm gnome org>
Date: Mon May 18 15:56:34 2009 -0500
[mallard] Finished off block_note
---
doc/mallard/C/mal_block_note.xml | 157 ++++++++++++++++++++++++++++++++-
xslt/mallard/html/mal2html-block.xsl | 13 ++-
2 files changed, 161 insertions(+), 9 deletions(-)
diff --git a/doc/mallard/C/mal_block_note.xml b/doc/mallard/C/mal_block_note.xml
index 190200b..799b3b5 100644
--- a/doc/mallard/C/mal_block_note.xml
+++ b/doc/mallard/C/mal_block_note.xml
@@ -3,7 +3,20 @@
id="mal_block_note">
<info>
- <version number="0.1" date="2007-02-21" status="stub"/>
+ <version number="0.1" date="2009-05-18" 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>Include notes, tips, warnings, and other parenthetical information.</desc>
</info>
<title>Notes</title>
@@ -18,6 +31,14 @@ mal_block_note = element note {
}
</code></synopsis>
+<p>The <code>note</code> element allows you to insert parenthetical block-level
+content into your document. Notes are visually distinct blocks, allowing readers
+to skip them or focus on them, depending on their needs. You can use notes to
+give tips, warn readers of potentially dangerous operations, point out known bugs,
+or otherwise provide additional information without interfering with the main text
+of your document.</p>
+
+
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
@@ -47,6 +68,10 @@ mal_block_note = element note {
<td><p>a note about a known bug in the software</p></td>
</tr>
<tr>
+ <td><p><code>"important"</code></p></td>
+ <td><p>important information highlighted in a note</p></td>
+ </tr>
+ <tr>
<td><p><code>"tip"</code></p></td>
<td><p>a general tip that may help the reader perform an operation better</p></td>
</tr>
@@ -68,19 +93,141 @@ mal_block_note = element note {
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
+
+ <p>Insert a basic note into your document:</p>
+
+ <example>
+ <code><![CDATA[
+<note>
+ <p>Information in this section is non-normative.</p>
+</note>
+]]></code>
+ <note>
+ <p>Information in this section is non-normative.</p>
+ </note>
+ </example>
+
+ <p>Include a note with extra information for advanced readers:</p>
+
+ <example>
+ <code><![CDATA[
+<note style="advanced">
+ <p>The Mallard schema is maintained in RELAX-NG Compact Syntax in
+ code blocks embedded within the specification.</p>
+</note>
+]]></code>
+ <note style="advanced">
+ <p>The Mallard schema is maintained in RELAX-NG Compact Syntax in
+ code blocks embedded within the specification.</p>
+ </note>
+ </example>
+
+ <p>Mention a known bug the reader is likely to encounter:</p>
+
+ <example>
+ <code><![CDATA[
+<note style="bug">
+ <title>Cannot Save Files</title>
+ <p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you
+ cannot actually save files. If you try to save your files, the application
+ will crash. We recommend memorizing all your data on a regular basis.</p>
+</note>
+]]></code>
+ <note style="bug">
+ <title>Cannot Save Files</title>
+ <p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you
+ cannot actually save files. If you try to save your files, the application
+ will crash. We recommend memorizing all your data on a regular basis.</p>
+ </note>
+ </example>
+
+ <p>Highlight a vital piece of information to ensure readers see it even
+ when skimming a document:</p>
+
+ <example>
+ <code><![CDATA[
+<note style="important">
+ <title>Supply Your Name and Email Address</title>
+ <p>Before making any commits to a git repository, make sure to
+ supply your name and email address so that your commits are
+ correctly attributed.</p>
+ <code>
+git config --global user.name <var>full_name</var>
+git config --global user.email <var>email_address</var></code>
+</note>
+]]></code>
+ <note style="important">
+ <title>Supply Your Name and Email Address</title>
+ <p>Before making any commits to a git repository, make sure to
+ supply your name and email address so that your commits are
+ correctly attributed.</p>
+ <code>
+git config --global user.name <var>full_name</var>
+git config --global user.email <var>email_address</var></code>
+ </note>
+ </example>
+
+ <p>Provide a helpful but non-essential tip:</p>
+
+ <example>
+ <code><![CDATA[
+<note style="tip">
+ <p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to
+ the currently playing track.</p>
+</note>
+]]></code>
+ <note style="tip">
+ <p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to
+ the currently playing track.</p>
+ </note>
+ </example>
+
+ <p>Warn the reader about dangerous operations:</p>
+
+ <example>
+ <code><![CDATA[
+<note style="warning">
+ <p>There is no way to recover files deleted with the
+ <cmd>shred</cmd> command.</p>
+</note>
+]]></code>
+ <note style="warning">
+ <p>There is no way to recover files deleted with the <cmd>shred</cmd> command.</p>
+ </note>
+ </example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
+
+ <p>Notes are displayed as block elements, with each of their child elements
+ being interpreted as block elements. When present, the title should be
+ displayed in a way that makes it clear that it is the title of the block.
+ Notes should have a border, background color, or other styling effect to
+ distinguish them from the surrounding block content. Notes often use an
+ icon to identify what type of note is being displayed.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
+
+ <p>The <code>note</code> element is similar to the
+ <code href="http://www.docbook.org/tdg/en/html/caution.html">caution</code>,
+ <code href="http://www.docbook.org/tdg/en/html/important.html">important</code>,
+ <code href="http://www.docbook.org/tdg/en/html/note.html">note</code>,
+ <code href="http://www.docbook.org/tdg/en/html/tip.html">tip</code>, and
+ <code href="http://www.docbook.org/tdg/en/html/warning.html">warning</code>
+ elements in DocBook. Rather than use separate elements, Mallard uses single
+ <code>note</code> element which can be specialized and extended through style
+ hints. This document recommends the style hints <code>advanced</code> and
+ <code>bug</code>, which have no counterpart in DocBook. This document does
+ not recommend separate <code>caution</code> and <code>warning</code> types,
+ as there is rarely a useful distinction in practice.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/xslt/mallard/html/mal2html-block.xsl b/xslt/mallard/html/mal2html-block.xsl
index dbe9968..8a1260d 100644
--- a/xslt/mallard/html/mal2html-block.xsl
+++ b/xslt/mallard/html/mal2html-block.xsl
@@ -82,9 +82,9 @@ div.listing-contents { margin: 0; padding: 0; }
div.note {
padding: 0.5em 6px 0.5em 6px;
border-top: solid 1px </xsl:text>
- <xsl:value-of select="$theme.color.gray_border"/><xsl:text>;
+ <xsl:value-of select="$theme.color.red_border"/><xsl:text>;
border-bottom: solid 1px </xsl:text>
- <xsl:value-of select="$theme.color.gray_border"/><xsl:text>;
+ <xsl:value-of select="$theme.color.red_border"/><xsl:text>;
background-color: </xsl:text>
<xsl:value-of select="$theme.color.yellow_background"/><xsl:text>;
}
@@ -98,10 +98,12 @@ div.note-inner {
background-image: url("</xsl:text>
<xsl:value-of select="$theme.icon.admon.note"/><xsl:text>");
}
-div.note-advanced div.note-inner { background-image: url("</xsl:text>
- <xsl:value-of select="$theme.icon.admon.tip"/><xsl:text>"); }
+div.note-advanced div.note-inner { <!-- background-image: url("</xsl:text>
+ <xsl:value-of select="$theme.icon.admon.advanced"/><xsl:text>"); --> }
div.note-bug div.note-inner { background-image: url("</xsl:text>
<xsl:value-of select="$theme.icon.admon.bug"/><xsl:text>"); }
+div.note-important div.note-inner { background-image: url("</xsl:text>
+ <xsl:value-of select="$theme.icon.admon.important"/><xsl:text>"); }
div.note-tip div.note-inner { background-image: url("</xsl:text>
<xsl:value-of select="$theme.icon.admon.tip"/><xsl:text>"); }
div.note-warning div.note-inner { background-image: url("</xsl:text>
@@ -312,6 +314,9 @@ FIXME
<xsl:when test="contains(concat(' ', @style, ' '), ' bug ')">
<xsl:text>bug</xsl:text>
</xsl:when>
+ <xsl:when test="contains(concat(' ', @style, ' '), ' important ')">
+ <xsl:text>important</xsl:text>
+ </xsl:when>
<xsl:when test="contains(concat(' ', @style, ' '), ' tip ')">
<xsl:text>tip</xsl:text>
</xsl:when>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]