GNOME.org
 

[gnome-doc-utils/mallard] [mallard] Finished off block_note

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]