owlscribble 0.9.0

data/HISTORY

@@ -0,0 +1,12 @@
+== 0.9.0 / 2007-November-25
+
+* Added each_wiki_link and each_wiki_command to handle these during processing
+  instead of forcing the user to change the document after it's been created.
+
+* Added support for [[[Odd! Page Name]] some link text] page links.
+
+* Updated to use TagTreeScanner v0.8 so controlling tag attributes is simpler.
+
+== 0.8.0 / 2005-July-4
+
+* First public release

data/Manifest.txt

@@ -0,0 +1,15 @@
+HISTORY
+Manifest.txt
+README.txt
+Rakefile
+TODO
+examples/markup.html
+examples/markup.owl
+examples/scribblify.rb
+examples/template.rhtml
+lib/owlscribble.rb
+test/test_lists.html
+test/test_lists.owl
+test/test_owlscribble.rb
+test/test_toc.html
+test/test_toc.owl

data/README.txt

@@ -0,0 +1,180 @@
+= OWLScribble
+Author::     Gavin Kistner  (mailto:phrogz@mac.com)
+Copyright::  Copyright (c)2005-2007 Gavin Kistner
+License::    MIT License
+Version::    0.9.0 (2007-November-25)
+
+== Overview
+
+OWLScribble converts a specific set of wiki text markup into HTML.
+(The syntax used in the markup is a knockoff of the markup used by OpenWiki;
+the 'OWL' in OWLScribble means "OpenWiki-like".)
+
+The OWLScribble.each_wiki_link method provides a way to customize the HTML
+produced for individual in-wiki page links. (Since the URLs for such links
+is custom to each site, and the user may wish to perform DB queries to control
+the display and/or linking of various links.)
+
+The OWLScribble.each_wiki_command method provides a way to handle special
+processing instructions used in the markup.
+
+
+== Features
+
+* Automatically wraps logical document sections in HTML tags for CSS styling.
+
+* Flexible markup allows non-standard wiki page names, with optional
+  alternative text displayed for wiki links.
+
+  * Control over the HTML used for wiki links via custom block processing.
+  
+* Mixed bulleted and numbered lists, with many list numbering styles.
+
+* HTML table support.
+
+* Arbitrary processing directives with a block to control the produced HTML.
+
+  * Built-in ##TableOfContents## directive uses the nested headings in the
+    document to produce a hierarchical hyperlinked TOC.
+
+* Access to a DOM-like tag hierarchy after parsing the markup but prior to
+  generating HTML, allowing arbitrary changes as necessary.
+
+
+== Example Usage
+
+  require 'owlscribble'
+  
+  # Tell the library how to handle links the way I like them:
+  OWLScribble.each_wiki_link do |tag, page_name, link_text|
+    tag.name  = "a"
+    tag.href  = "page/view/#{CGI.escape(page_name)}"
+    tag.title = "View #{page_name.dewikiword}"
+    # tag.text is already set to something reasonable
+  end
+  
+  # Tell the library how to handle commands the way I need:
+  OWLScribble.each_wiki_command do |tag, command, params|
+    case command
+      when 'Include' # Include(page_name) or Include(page_name,rev)
+        tag.name  = 'div'
+        tag.class = 'sub_page'
+        page_name, revision = params
+        # All elements in the params array are strings
+        revision = Integer( revision ) rescue nil
+        tag.text = fetch_page( page_name, revision )
+      else
+        tag.name  = 'span'
+        tag.class = 'unhandled_command'
+        tag.text = "###{command}( #{params.join ', '} )##"
+      end
+    end
+  end
+  
+  owl = OWLScribble.new( the_string_to_parse )
+  puts owl.to_html
+
+== Markup
+
+See the link:../examples/markup.html file for documentation on the markup itself.
+
+This page itself was produced using OWL markup; see link:../examples/markup.owl to see the
+source.
+
+== Customizing the Document
+=== Wiki Links
+OWLScribble supports three ways to specify a link to a specific 'page', indicated by name:
+* <b><tt>WikiWords</tt></b> <i>(aka CamelCase)</i> are assumed to be page links.
+* <b><tt>[WikiWord some other text]</tt></b> creates a link to a page with alternate text.
+* <b><tt>[[Some Page! Name]]</tt></b> allows link creation to pages whose names are not WikiWords.
+<i>(For more information on creating links, see the link:../docs/markup.html documentation.)</i>
+
+Because OWLScribble cannot know how to create URLs for such items, you must either supply an
+_each_wiki_link_ block _before intitialization_ (see example above) to transform tags on the fly,
+or else spin through the <tt>wiki_links</tt> property on the OWLScribble instance to manipulate
+them before creating the final HTML.
+
+If you don't supply an _each_wiki_link_ block, the following example shows how to mutate these
+non-HTML tags into HTML anchors with a custom url, leaving the text of the link untouched:
+
+ require 'cgi'
+ owl.wiki_links.each{ |tag|
+   tag.name = :a
+   page = tag.attributes[ :page ]
+   tag.attributes[ :href ] = "view?#{CGI.escape(page)}"
+   tag.attributes.delete( :page )
+ }
+
+=== Wiki Commands
+In addition to links to wiki pages, OWLScribble allows the user to
+specify ommands using the following format. For example:
+* <tt>##TableOfContents##</tt> - include a table of contents here
+* <tt>##DEPRECATED##</tt> - mark this page for future deletion
+* <tt>##Include(PageName)##</tt> - include the contents of another page at this location
+* <tt>##RedirectTo(PageName)##</tt> - show the specified page instead
+* <tt>##AnyCommand(Param1,Param2,Param3)##</tt> - anything you want
+
+OWLScribble handles the +TableOfContents+ command automatically, building a table of contents
+from the hierarchy of heading levels and replacing any <tt>##TableOfContents##</tt>
+commands with copies of that TOC. Additionally, every section following
+a header tag is wrapped in a <tt><div class="section">...</div></tt> block,
+providing a nested hierarchy of sections in the page itself. (This is 
+primarily useful for applying CSS to sections, such as visual indentation.)
+
+For the other commands, it is up to you to handle them. The simplest method is (as with links)
+to supply an _each_wiki_command_ block to the OWLScribble class before creating any instances.
+(See the example above.) Also as with with the links, you may also choose to run through the
++wiki_commands+ array after initialization but before calling #to_html, changing the non-HTML
+<tt>"wiki_command"</tt> tags into something else.
+
+With the default _each_wiki_command_ block, these tags have a <tt>:do</tt> attribute
+which is the string name of the command, and may have a <tt>:params</tt> attribute that
+contains a comma-delimited list of parameters supplied by the user. If they are not removed or
+changed, these tags will show up in the HTML output. For example, this input text:
+ == Engineering ==
+ Here's the home page from engineering:
+ 
+ ##Include(EngineeringHome)##
+
+will produce the following HTML:
+ <h2 id="Engineering">Engineering</h2>
+ <div class="section">
+ <p>Here's the home page from engineering:</p>
+ <wiki_command do="Include" param="EngineeringHome">##Include(EngineeringHome)##</wiki_command>
+ </div>
+
+The presence of these tags should not affect the functioning or rendering
+of the produced HTML in any modern browser, but it will be syntactically invalid.
+
+
+== Requirements
+
+* OWLScribble is based on (and hence requires) the +TagTreeScanner+ library
+  (http://tagtreescanner.rubyforge.org). Installing this gem should have
+  already informed you of the requirement and given you a chance to install it.
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2005-2007 Gavin Kistner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,17 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/owlscribble.rb'
+
+Hoe.new('owlscribble', OWLScribble::VERSION) do |p|
+  p.rubyforge_name = 'owlscribble'
+  p.author = 'Gavin Kistner'
+  p.email  = 'phrogz@mac.com'
+  p.summary = "Converts a specific syntax of text markup into HTML. (The syntax is similar to OpenWiki's.)"
+  p.description = IO.read( 'README.txt' )[ /= Overview\n(.+?)^=/m, 1 ].rstrip
+  p.changes     = IO.read( 'HISTORY' )[ /^=[^\n]+\n+(.+?)(?:^=|\Z)/m, 1 ].rstrip
+  p.remote_rdoc_dir = ''
+end
+
+# vim: syntax=Ruby

data/TODO

@@ -0,0 +1,7 @@
+* Speed optimizations, once it's feature-complete
+
+* Process indented paragraphs like lists, just to calculate minimal depth from many spaces
+
+* Inline commands for <br>? Some auto-br inclusion?
+
+* More unit tests (especially around each_wiki_link and each_wiki_command)

data/examples/markup.html

@@ -0,0 +1,343 @@
+<html><head><title>Welcome to the Jungle</title>
+<style type="text/css">
+	body	{ margin:1em 2em; font-size:90%; font-family:'Trebuchet MS', serif; margin-bottom:30em }
+
+	a:link, a:visited	{ color:#009 }
+	a.newwikilink	{ color:#900 }
+	
+	h1,h2,h3,h4,h5,h6	{ margin-bottom:0.2em; margin-top:2em; border-bottom:1px solid #999; font-family:sans-serif }
+	h1	{ font-size:120% }
+	h2	{ font-size:110% }
+	h3,h4	{ font-size:100% }
+	h5,h6	{ font-size:90% }
+	h4,h5,h6 	{ font-style:italic }
+
+	ul, ol	{ margin:0; padding:0; margin-left:1.5em; margin-bottom:0.8em }
+	ul ol, ol ul, ul ul, ol ol 	{ margin-left:1.5em }
+	li	{ margin-bottom:0 }
+	p	{ margin:0; margin-bottom:0.7em }
+	pre	{ background:#ffd; padding:0.5em; border:1px solid #993 }
+	.todo	{ font-weight:bold; color:#900 }
+	.section	{ margin-left:1em }
+	table	{ border-collapse:collapse; margin-bottom:1em }
+	td	{ border:1px solid #ccc; padding:0.1em 0.5em; font-size:85% }
+	pre, code, tt	{ color:#060 }
+
+	dt	{ font-weight:bold }
+
+	.indent1	{ margin-left:2em }
+	.indent2	{ margin-left:4em }
+	.indent3	{ margin-left:6em }
+	.indent4	{ margin-left:8em }
+	.indent5	{ margin-left:10em }
+	.indent6	{ margin-left:12em }
+</style>
+</head><body>
+<h1 id="TableofContents">Table of Contents</h1>
+<div class="section">
+<div class="toc"><ul><li><a href="#TableofContents">Table of Contents</a></li><li><a href="#WelcometoOWLScribble">Welcome to OWLScribble!</a><ul><li><a href="#WhatisOWLScribble">What is OWLScribble?</a></li><li><a href="#SupportedMarkup">Supported Markup</a><ul><li><a href="#Paragraphs">Paragraphs</a><ul><li><a href="#IndentedParagraphs">Indented Paragraphs</a></li></ul></li><li><a href="#PreformattedText">Preformatted Text</a></li><li><a href="#BasicInlineStyling">Basic Inline Styling</a></li><li><a href="#Headings">Headings</a></li><li><a href="#Linking">Linking</a><ul><li><a href="#PreventingLinking">Preventing Linking</a></li></ul></li><li><a href="#Lists">Lists</a><ul><li><a href="#BulletedLists">Bulleted Lists</a></li><li><a href="#NumberedLists">Numbered Lists</a></li><li><a href="#MixingLists">Mixing Lists</a></li><li><a href="#DefinitionLists">Definition Lists</a></li></ul></li><li><a href="#Tables">Tables</a></li></ul></li><li><a href="#ProcessingDirectives">Processing Directives</a></li><li><a href="#Miscellaneous">Miscellaneous</a></li></ul></li></ul></div>
+</div>
+<h1 id="WelcometoOWLScribble">Welcome to OWLScribble!</h1>
+<div class="section">
+<p><i>An introduction to the <span>OWLScribble</span> markup language.</i></p>
+<h2 id="WhatisOWLScribble">What is OWLScribble?</h2>
+<div class="section">
+<p><span>OWLScribble</span> is a wiki markup language <i>based on</i> the markup used by <a href="hTTp://www.openwiki.org/">OpenWiki</a>. It was designed for use with the <span>SewWiki</span> project by <a href="dummylinktopage?GavinKistner" class="newwikilink">Gavin Kistner</a>.</p>
+</div>
+<h2 id="SupportedMarkup">Supported Markup</h2>
+<div class="section">
+<h3 id="Paragraphs">Paragraphs</h3>
+<div class="section">
+<pre>Paragraphs start on a line of their own
+and may be continued onto multiple
+consecutive lines.
+
+A double line break indicates the start
+of a new paragraph.
+
+  If the start of the text is indented at all,
+  however, then it is treated as preformatted
+  text.</pre>
+<p>Paragraphs start on a line of their own
+and may be continued onto multiple
+consecutive lines.</p>
+<p>A double line break indicates the start
+of a new paragraph.</p>
+<pre>If the start of the text is indented at all,
+however, then it is treated as preformatted
+text.
+</pre>
+<h4 id="IndentedParagraphs">Indented Paragraphs</h4>
+<div class="section">
+<pre>  : An exception to the indented-paragraph rule is this.
+    : Paragraphs (on a single line)
+    : with whitespace preceding a colon
+    : are indented based on the amount of space
+  : But, as seen here, each line is its own paragraph.</pre>
+<p class="indent1">An exception to the indented-paragraph rule is this.</p>
+<p class="indent2">Paragraphs (on a single line)</p>
+<p class="indent2">with whitespace preceding a colon</p>
+<p class="indent2">are indented based on the amount of space</p>
+<p class="indent1">But, as seen here, each line is its own paragraph.</p>
+</div>
+</div>
+<h3 id="PreformattedText">Preformatted Text</h3>
+<div class="section">
+<pre>   {{{
+   for ( var i=0; i&lt;10; ++i ){
+     alert( 'hi!' );
+   }
+   }}}</pre>
+<pre>for ( var i=0; i&lt;10; ++i ){
+  alert( 'hi!' );
+}</pre>
+<p>To be clear about the start and end, you may
+specify preformatted text by wrapping it in
+<tt>{{{...}}}</tt> over multiple lines.</p>
+<p>Such text is automatically unindented by the
+amount of indentation on the end markers.</p>
+</div>
+<h3 id="BasicInlineStyling">Basic Inline Styling</h3>
+<div class="section">
+<pre>This text **is bold**, this //is italic//,
+and --this has been struck--.
+
+//You can start a paragraph with an inline
+style, but you cannot wrap it across lines.//
+
+This is a @@code reference@@,
+as is {{{this text}}}.
+
+A double-exclamation point is a special
+'todo' item. !!Add more examples!!
+
+You can also ^^superscript^^ and
+__subscript__ text, like H__2__O
+or e^^pi*i^^.</pre>
+<p>This text <b>is bold</b>, this <i>is italic</i>,
+and <strike>this has been struck</strike>.</p>
+<p><i>You can start a paragraph with an inline</i>
+style, but you cannot wrap it across lines.<i></i></p>
+<p>This is a <tt>code reference</tt>,
+as is <tt>this text</tt>.</p>
+<p>A double-exclamation point is a special
+'todo' item. <span class="todo">TODO - Add more examples</span></p>
+<p>You can also <sup>superscript</sup> and
+<sub>subscript</sub> text, like H<sub>2</sub>O
+or e<sup>pi*i</sup>.</p>
+<ul>
+<li><i>Unlike <span>OpenWiki</span>, you are not allowed to underline text. Sorry, but underlining is reserved for links in hyperlinked documents.</i></li>
+</ul>
+</div>
+<h3 id="Headings">Headings</h3>
+<div class="section">
+<pre>= Heading Level 1 =
+== Heading Level 2 ==
+=== Heading Level 3 ===
+==== Heading Level 4 ====
+===== Heading Level 5 =====
+====== Heading Level 6 ======</pre>
+<p>Headings must begin at the start of the line. Markup inside headings is ignored. (For example,
+<tt>== My //Sweet// Heading ==</tt> will not make the word italic, but will instead show the <tt>//</tt> characters in the output.)</p>
+</div>
+<h3 id="Linking">Linking</h3>
+<div class="section">
+<pre> * Visit SiteMap, HomePage, or WhereDoIBegin to get started.
+ * Visit the [[What is a Wiki?]] page if you're really lost.
+ * Visit hTTp://www.google.com to find stuff on the web.
+ * The [hTTp://www.microsoft.com company that shall not be named] thinks they can beat Google.
+ * This page was edited by [GavinKistner the Wiki Gardener].
+ * See [[[Foo/Bar/Jim/Jam]] the Jam page] for more deliciousness.</pre>
+<ul>
+<li>Visit <a href="dummylinktopage?SiteMap" class="newwikilink">Site Map</a>, <a href="dummylinktopage?HomePage" class="newwikilink">Home Page</a>, or <a href="dummylinktopage?WhereDoIBegin" class="newwikilink">Where Do I Begin</a> to get started.</li>
+<li>Visit the <a href="dummylinktopage?What+is+a+Wiki%3F" class="newwikilink">What is a Wiki?</a> page if you're really lost.</li>
+<li>Visit <a href="hTTp://www.google.com">www.google.com</a> to find stuff on the web.</li>
+<li>The <a href="hTTp://www.microsoft.com">company that shall not be named</a> thinks they can beat Google.</li>
+<li>This page was edited by <a href="dummylinktopage?GavinKistner" class="newwikilink">the Wiki Gardener</a>.</li>
+<li>See <a href="dummylinktopage?Foo%2FBar%2FJim%2FJam" class="newwikilink">the Jam page</a> for more deliciousness.</li>
+</ul>
+<p><span>OWLScribble</span> supports three styles of specifying a link:</p>
+<ol>
+<li>Text that looks like <span>URLs</span> are automatically linked. You must use a capital 'T' and lowercase letters in the protocol to get it recognized. (It's annoying, but designed to stop spam bots.) So <span>http://www.google.com/</span> will not be linked, but <tt>hTTp://www.google.com</tt> will yield: <a href="hTTp://www.google.com">www.google.com</a><ul>
+<li><i>Supported protocols are http, https, and ftp.</i></li>
+</ul></li>
+<li><b><span>WikiWords</span></b> are automatically treated as links to other pages in the Wiki, and expanded out. For example, typing <tt>CapitalizedWordsScrunchedTogether</tt> produces "<a href="dummylinktopage?CapitalizedWordsScrunchedTogether" class="newwikilink">Capitalized Words Scrunched Together</a>".<ul>
+<li><i>The <span>OWLScribble</span> class simply turns the above into the 'HTML' code: <tt>&lt;wiki_link page="CapitalizedWordsScrunchedTogether"&gt;Capitalized Words Scrunched Together&lt;/wiki_link&gt;</tt>. It is up to the consumer of <span>OWLScribble</span> to run through the <tt>#wiki_links</tt> collection and replace the above with something reasonable (such as an HTML anchor) after doing whatever it needs to do (such as a db lookup).</i></li>
+</ul></li>
+<li>If you want to create a wiki page whose name doesn't look like a <span>WikiWord</span>, you can wrap it in double square brackets, like <tt>See the [[Table of Contents]] page</tt>.<ul>
+<li><i>Again, <span>OWLScribble</span> turns the above into: <tt>&lt;wiki_link page="Table of Contents"&gt;Table of Contents&lt;/wiki_link&gt;</tt>, leaving it up to the consumer of <span>OWLScribble</span> to change that tag into something better.</i></li>
+<li>As seen in the last example above, you can use the double-square-bracket wiki link style along with outer brackets to supply different page text. <span>OWLScribble</span> turns the last example above into: <tt>&lt;wiki_link page="Foo/Bar/Jim/Jam"&gt;the Jam page&lt;/wiki_link&gt;</tt>.<i></i></li>
+</ul></li>
+</ol>
+<p>With either <span>URLs</span> or <span>WikiWords</span>, you can optionally use an alternative description for the link text. As shown above, place a single set of square brackets around what you want linked, with the URL or <span>WikiWord</span> as the first item.</p>
+<h4 id="PreventingLinking">Preventing Linking</h4>
+<div class="section">
+<pre>Sometimes you want to write something that looks like a
+~WikiWord (such as ~OpenWiki) but you don't want it to
+appear as a link to a page in the wiki.
+
+You can either wrap it in preformatted text delimiters
+like @@{{{OpenWiki}}}@@, or place a tilde (~) character right
+before it, as in {{{~OpenWiki}}}.</pre>
+<p>Sometimes you want to write something that looks like a
+<span>WikiWord</span> (such as <span>OpenWiki</span>) but you don't want it to
+appear as a link to a page in the wiki.</p>
+<p>You can either wrap it in preformatted text delimiters
+like <tt>{{{OpenWiki}}}</tt>, or place a tilde (~) character right
+before it, as in <tt>~OpenWiki</tt>.</p>
+</div>
+</div>
+<h3 id="Lists">Lists</h3>
+<div class="section">
+<h4 id="BulletedLists">Bulleted Lists</h4>
+<div class="section">
+<pre>         1         2         3         4         5         6     
+12345678901234567890123456789012345678901234567890123456789012345
+  * Bullet lists need **at least one space** before the asterisk.
+    * **A space** must appear after the asterisk.
+      * They may be nested to an arbitrary depth.
+  * Tabs may also be used for indentation.
+  * Mixing tabs and spaces is asking for trouble.</pre>
+<ul>
+<li>Bullet lists need <b>at least one space</b> before the asterisk.<ul>
+<li><b>A space</b> must appear after the asterisk.<ul>
+<li>They may be nested to an arbitrary depth.</li>
+</ul></li>
+</ul></li>
+<li>Tabs may also be used for indentation.</li>
+<li>Mixing tabs and spaces is asking for trouble.</li>
+</ul>
+</div>
+<h4 id="NumberedLists">Numbered Lists</h4>
+<div class="section">
+<pre>         1         2         3         4         5         6     
+12345678901234567890123456789012345678901234567890123456789012345
+  1. Numbered lists must also have a space before the number.
+  1. The actual number doesn't matter...
+    3. ...but the period after the number does.
+    1. As well as the space after the period.
+  # You can also use the 'octothorp' if you like.
+    # //(A fancy name for the 'sharp' or 'pound' symbol.)
+  # Other types of numbered lists are supported beyond arabic.
+    a. For arabic lists, you can use 1, 2, 3, ... 23, etc.
+    a. but for the following, you must use the actual character.
+    a. A lowercase 'a' is for lowercase alphabetical lists.
+    A. An uppercase 'A' is for uppercase alphabetical lists.
+    i. A lowercase 'i' is for lowercase roman numeral lists.
+    I. An uppercase 'I' is for uppercase roman numeral lists.</pre>
+<ol>
+<li>Numbered lists must also have a space before the number.</li>
+<li>The actual number doesn't matter...<ol>
+<li>...but the period after the number does.</li>
+<li>As well as the space after the period.</li>
+</ol></li>
+<li>You can also use the 'octothorp' if you like.<ol>
+<li><i>(A fancy name for the 'sharp' or 'pound' symbol.)</i></li>
+</ol></li>
+<li>Other types of numbered lists are supported beyond arabic.<ol>
+<li type="a">For arabic lists, you can use 1, 2, 3, ... 23, etc.</li>
+<li type="a">but for the following, you must use the actual character.</li>
+<li type="a">A lowercase 'a' is for lowercase alphabetical lists.</li>
+<li type="A">An uppercase 'A' is for uppercase alphabetical lists.</li>
+<li type="i">A lowercase 'i' is for lowercase roman numeral lists.</li>
+<li type="I">An uppercase 'I' is for uppercase roman numeral lists.</li>
+</ol></li>
+</ol>
+</div>
+<h4 id="MixingLists">Mixing Lists</h4>
+<div class="section">
+<pre>         1         2         3         4         5         
+12345678901234567890123456789012345678901234567890123456789
+  * Bulleted and numbered lists may be alternately nested
+    1. And (as seen above)...
+    i. ...you can mix numbered list styles on the fly
+  * But woe unto you if you try to mix a bullet...
+  1. ...and a number in the same list.
+    * //Sorry buddy, but that doesn't fly.//</pre>
+<ul>
+<li>Bulleted and numbered lists may be alternately nested<ol>
+<li>And (as seen above)...</li>
+<li type="i">...you can mix numbered list styles on the fly</li>
+</ol></li>
+<li>But woe unto you if you try to mix a bullet...</li>
+<li>...and a number in the same list.<ul>
+<li><i>Sorry buddy, but that doesn't fly.</i></li>
+</ul></li>
+</ul>
+</div>
+<h4 id="DefinitionLists">Definition Lists</h4>
+<div class="section">
+<pre>         1         2         3         4         5         
+12345678901234567890123456789012345678901234567890123456789
+  ; Semantic : of or relating to meaning in language
+  ; Grok : to understand //completely//
+  ;      : to inherently and almost intuitively comprehend</pre>
+<dl>
+<dt>Semantic</dt>
+<dd>of or relating to meaning in language</dd>
+<dt>Grok</dt>
+<dd>to understand <i>completely</i></dd>
+<dd>to inherently and almost intuitively comprehend</dd>
+</dl>
+<ul>
+<li><i>Unlike <span>OpenWiki</span>, you cannot 'nest' or indent definition lists.</i></li>
+</ul>
+</div>
+</div>
+<h3 id="Tables">Tables</h3>
+<div class="section">
+<pre>|| **Age** || **Sex** || **Weight** ||
+|| 32      ||    M    ||        180 ||
+|| 30 || F || 150 ||
+|||| //average// || **165** ||</pre>
+<table>
+<tr>
+<td><b>Age</b></td>
+<td><b>Sex</b></td>
+<td><b>Weight</b></td>
+</tr>
+<tr>
+<td>32</td>
+<td>M</td>
+<td>180</td>
+</tr>
+<tr>
+<td>30</td>
+<td>F</td>
+<td>150</td>
+</tr>
+<tr>
+<td colspan="2"><i>average</i></td>
+<td><b>165</b></td>
+</tr>
+</table>
+<p>You don't have to line up the bars from one row to the next, but you may
+if you want the text representation to look clean. As seen above,
+you can cause a cell to span multiple columns.</p>
+</div>
+</div>
+<h2 id="ProcessingDirectives">Processing Directives</h2>
+<div class="section">
+<p>A processing directive appears as a pair of pound symbols with a command
+inside, optionally followed by parameters to that command inside
+parentheses. For example:</p>
+<pre>##TableOfContents##
+##IncludePage(ProcessingDirectives)##</pre>
+<p><span>OWLScribble</span> currently recognizes the following directives:</p>
+<ul>
+<li><tt>##TableOfContents##</tt> - replaces the directive with a nested list representing the hierarchy of headers in the document, with links to those headers</li>
+<li><tt>##DEPRECATED##</tt> - indicates that the document is no longer needed, and should be removed</li>
+<li><tt>##BALETED##</tt> - <i>same as DEPRECATED</i></li>
+<li><tt>##IncludePage(PageName)##</tt> - indicates that the contents of the other page should be included in this location</li>
+</ul>
+<p>Note that <span>OWLScribble</span> only handles the <tt>TableOfContents</tt> directive natively. The other directives are replaced with an empty non-HTML 'wiki_command' tag, such as <tt>&lt;wiki_command do="TableOfContents" /&gt;</tt> or <tt>&lt;wiki_command do="IncludePage" param="CommonFooter" /&gt;</tt>. It is up to the consumer of <span>OWLScribble</span> to handle and/or replace such tags with meaningful information.</p>
+<p class="indent1"><i>There are two ways to handle these tags. One way is to parse and modify the HTML produced by <span>OWLScribble</span> as a string. This is effective, but not recommended.</i></p>
+<p class="indent1"><i>The recommended mechanism for handling processing directives is to spin through the <tt>#wiki_commands</tt> collection of the <span>OWLScribble</span> object after initialization, processing the commands and replacing the tags as desired. Once this is done, call the <tt>#to_s</tt> or <tt>#to_html</tt> methods on the <span>OWLScribble</span> instance to get the final output.</i></p>
+</div>
+<h2 id="Miscellaneous">Miscellaneous</h2>
+<div class="section">
+<p>HTML entities are not needed (and do not work) inside <span>OWLScribble</span>; you can type <tt>"this &amp; that"</tt> and it will produce the HTML <tt>this &amp;amp; that</tt>, displaying as "this &amp; that". Typing <tt>&amp;amp;</tt> will actually show "&amp;amp;".</p>
+</div>
+</div>
+
+</body></html>