OWLScribble converts a specific set of text markup into HTML. (The syntax used in the markup is a knockoff of the markup used by OpenWiki, so the ‘OWL’ in OWLScribble means "OpenWiki-like".)

The tree of elements created during parsing is made available, along with collections for specific types of elements, such as a list of all wiki-commands or wiki page links. This lets you modify the element tree (e.g. perform a database lookup on pages and replace the links with html anchors to your URL) after parsing, but before creating the HTML string.

Usage

Basic Example:

 owl = OWLScribble.new( the_string_to_parse )
 puts owl.to_html

Modifying the Tree:

 require 'uri'
 owl.wiki_links.each{ |tag|
   tag.tag_name = :a
   page = tag.attributes[ :page ]
   tag.attributes[ :href ] = "view?#{URI.escape(page)}"
   tag.attributes.delete( :page )
 }

 owl.wiki_commands.each{ |tag|
   command = tag.attributes[ :do ]
   params  = tag.attributes[ :param ]
   # ...
 }

 puts owl.to_html

Wiki Links

OWLScribble supports three ways to specify a link to a specific ‘page’, indicated by name:

• WikiWords (aka CamelCase) are assumed to be page links.
• [WikiWord some other text] creates a link to a page with alternate text.
• [[Some Page! Name]] allows link creation to pages whose names are not WikiWords.

(For more information on creating links, see the ../markup.html file supplied with this library.)

Because OWLScribble cannot know how to create URLs for such items, it simply wraps the text to link in a special "wiki_link" tag, with a :page attribute holding the name of the page to be linked to.

Instances of the OWLScribble class have a wiki_links property that provides you with an array of such links, so that you can iterate these links and manipulate them before generating HTML.

The following example snippet shows how to mutate these non-HTML tags into HTML anchors with a custom url, leaving the text of the link untouched:

 require 'uri'
 owl.wiki_links.each{ |tag|
   tag.tag_name = :a
   page = tag.attributes[ :page ]
   tag.attributes[ :href ] = "view?#{URI.escape(page)}"
   tag.attributes.delete( :page )
 }

Wiki Commands

In addition to links to wiki pages, OWLScribble allows the user to specify three commands:

• #TableOfContents## - include a table of contents here
• #DEPRECATED## - mark this page for future deletion
• #Include(PageName)## - include the contents of another page at this location
• #RedirectTo(PageName)## - show the specified page instead

OWLScribble handles the first automatically, building a table of contents from the hierarchy of heading levels, and replacing any #TableOfContents## commands with copies of that TOC. Additionally, every section following a header tag is wrapped in a <div class="section">…</div> 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. Instances of the OWLScribble class provide a wiki_commands property, which is an array of "wiki_command" tags. These tags have a :do attribute which is the string name of the command, and (for Include and RedirectTo) a :param attribute.

If they are not removed, 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"></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.

\OWLScribble Markup

For details on the markup used by OWLScribble, please see the ../markup.html file.