owlscribble

= OWLScribble Author:: Gavin Kistner (mailto:[e-mail]) Copyright:: Copyright (c)2005-2007 Gavin Kistner License:: MIT License Version:: 0.9.1 (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. That page was itself created 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:

• 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 link:../examples/markup.html documentation.)

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 wiki_links 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:

• ##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
• ##AnyCommand(Param1,Param2,Param3)## - anything you want

OWLScribble handles the +TableOfContents+ command 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

...

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 "wiki_command" tags into something else.

With the default each_wiki_command block, these tags have a :do attribute which is the string name of the command, and may have a :params 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:

Engineering

Here's the home page from engineering:

##Include(EngineeringHome)##

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.